Build it

Every command and file, in order. Use Git Bash, macOS Terminal or a Linux shell; Node 22.18 or newer (Node 24 recommended). Replace YOUR-USER with your GitHub username. Choosing the next version number, which you do in steps 11 and 13, is also a Practice exercise you can run in your browser.

1. Create the repo and the issue (on GitHub)

   gh repo create makes the GitHub repository and clones it. The issue states the goal and how we will know it is done (GitHub: remotes, Planning on GitHub). GitHub Pages needs a public repository on a free plan; check your plan if you want a private one.

   TerminalCopy

   gh repo create store-stock-checker --public --clone --description "Look up an article's stock at a store"
   cd store-stock-checker
   gh label create api --color 1d76db --description "The stock API"
   gh issue create --title "Look up an article's stock at a store" --label enhancement --label api \
     --body "Staff enter a store code (S014) and an article code (A1001) and see name, quantity and price.
   Acceptance: a GET endpoint returns JSON; unknown pairs return 404; bad codes return 400; a page shows the result or a clear error."

   Expected: GitHub prints the new issue's link, ending in /issues/1. enhancement is one of GitHub's default labels; api is the one we just created.

2. Scaffold the project

   One package.json with every script the team needs, so "how do I run the checks?" always has the same answer: npm run check. Pin the Node version in .nvmrc (Node.js and npm).

   TerminalCopy

   npm init -y
   npm i -D typescript@^5.9.3 typescript-eslint eslint @eslint/js globals @types/node@24
   echo 24 > .nvmrc
   printf 'node_modules/\n.env\n_site/\ncoverage/\n' > .gitignore

   OutputCopy

   added 99 packages, and audited 100 packages in 9s
   
   31 packages are looking for funding
     run `npm fund` for details
   
   found 0 vulnerabilities

   Then edit package.json so it looks like this. "type": "module" makes every .js and .ts file an ES module (Prototypes, classes and modules). We pin TypeScript 5.9, the line this course uses. Plain npm i -D typescript would pick the newest major (7 at the time of writing), and the current typescript-eslint release accepts only TypeScript below 6.1, so check that pair whenever you upgrade either one.

   JSONCopy

   {
     "name": "store-stock-checker",
     "version": "0.0.0",
     "private": true,
     "description": "Look up one article's stock at one store: a small API and a page",
     "type": "module",
     "engines": {
       "node": ">=22.18"
     },
     "scripts": {
       "start": "node src/main.ts",
       "dev": "node --watch src/main.ts",
       "test": "node --test",
       "lint": "eslint .",
       "typecheck": "tsc --noEmit",
       "check": "npm run lint && npm run typecheck && npm test"
     },
     "devDependencies": {
       "@eslint/js": "^10.0.1",
       "@types/node": "^24.19.1",
       "eslint": "^10.12.0",
       "globals": "^17.13.0",
       "typescript": "^5.9.3",
       "typescript-eslint": "^8.71.1"
     }
   }

   tsconfig.jsoneslint.config.js

   JSONCopy

   {
     "compilerOptions": {
       "target": "esnext",
       "module": "nodenext",
       "noEmit": true,
       "rewriteRelativeImportExtensions": true,
       "erasableSyntaxOnly": true,
       "verbatimModuleSyntax": true,
       "strict": true,
       "resolveJsonModule": true,
       "types": ["node"],
       "skipLibCheck": true
     },
     "include": ["src", "test"]
   }

   The tsconfig options are the ones the Node docs recommend for type stripping: noEmit (Node runs the source, so tsc only checks), erasableSyntaxOnly (no TypeScript features that Node cannot simply delete, such as enum), and verbatimModuleSyntax (type-only imports must say import type). Add a short README and a one-line placeholder src/main.ts so the type check has a file to read, then run the checks once and make the first commit directly on main. It is the only commit that will ever go there without a PR. (In this lesson we run the three checks separately and pass --test-reporter=tap, which prints plain ok and not ok lines; npm run check runs the same three with the default reporter's tick marks.) With no tests yet, the runner finds zero and passes.

   TerminalCopy

   npm run lint; npm run typecheck; npm test -- --test-reporter=tap

   OutputCopy

   > store-stock-checker@0.0.0 lint
   > eslint .
   
   > store-stock-checker@0.0.0 typecheck
   > tsc --noEmit
   
   > store-stock-checker@0.0.0 test
   > node --test --test-reporter=tap
   
   1..0
   # tests 0
   # pass 0
   # fail 0

   TerminalCopy

   git add -A
   git commit -m "chore: scaffold project with TypeScript, ESLint and README"
   git push -u origin main

3. Add CI in its own small PR

   CI comes first, so every later PR is checked. The workflow runs lint, the type check and the tests on Node 22 and 24 (GitHub Actions: continuous integration). permissions: contents: read gives the job's token the least it needs (Deploying and securing).

   YAMLCopy

   # .github/workflows/ci.yml: lint, type check and test every PR and every push to main
   name: CI
   on:
     pull_request:
     push:
       branches: [main]
   
   permissions:
     contents: read            # least privilege: CI only reads the code
   
   concurrency:
     group: ci-${{ github.ref }}
     cancel-in-progress: true  # a new push cancels the old run for the same branch
   
   jobs:
     check:
       runs-on: ubuntu-latest
       strategy:
         matrix:
           node: [22, 24]      # the two LTS lines we support
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with:
             node-version: ${{ matrix.node }}
             cache: npm
         - run: npm ci
         - run: npm run lint
         - run: npm run typecheck
         - run: npm test

   Check the file with actionlint (also from the CI lesson) before pushing; a typo in YAML otherwise shows up only as a failed run on GitHub.

   TerminalCopy

   git switch -c ci/add-workflow
   actionlint -verbose
   git add .github && git commit -m "ci: lint, type check and test on Node 22 and 24"
   git push -u origin ci/add-workflow
   gh pr create --fill --base main

   OutputCopy

   verbose: Found total 0 errors in 24 ms for .github/workflows/ci.yml
   verbose: Found total 0 errors in 50 ms for .github/workflows/release.yml
   verbose: Found 0 errors in 2 files

   On GitHub: PR #2 opens and two checks appear, check (22) and check (24), one per matrix entry. When both are green, merge with gh pr merge 2 --squash --delete-branch.

4. Protect main

   Now that CI exists, make it required. This ruleset (see Branching strategies, releases and versions) blocks direct pushes and force pushes to the default branch, requires one approval and resolved conversations, allows only squash merges, and requires both CI checks to pass on the latest code. We validated this JSON against GitHub's published REST API schema.

   JSONCopy

   {
     "name": "protect main",
     "target": "branch",
     "enforcement": "active",
     "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
     "rules": [
       { "type": "deletion" },
       { "type": "non_fast_forward" },
       { "type": "pull_request", "parameters": {
           "required_approving_review_count": 1,
           "dismiss_stale_reviews_on_push": true,
           "require_code_owner_review": false,
           "require_last_push_approval": false,
           "required_review_thread_resolution": true,
           "allowed_merge_methods": ["squash"] } },
       { "type": "required_status_checks", "parameters": {
           "strict_required_status_checks_policy": true,
           "required_status_checks": [ { "context": "check (22)" }, { "context": "check (24)" } ] } }
     ]
   }

   TerminalCopy

   gh api repos/{owner}/{repo}/rulesets --method POST --input ruleset.json

   On GitHub: the response is the new ruleset as JSON with an id, and it appears under the repository's Settings, Rules, Rulesets. On a solo practice repo you cannot approve your own PR, so either add a second account as a collaborator or set required_approving_review_count to 0 while practising.

5. Branch for the issue and build the stock lookup

   The branch name carries the issue number. The business rule lives in its own module with no HTTP in it, so it is easy to test. A Map gives one lookup per request (Performance and memory), and inputs are checked before use (Security and quality).

   TerminalCopy

   git switch -c feat/1-stock-api

   src/stock.tstest/stock.test.ts

   TypeScriptCopy

   // src/stock.ts: the business rule, with no HTTP in it, so it is easy to test
   import rows from './data/stock.json' with { type: 'json' };
   
   export interface StockRow {
     siteId: string;       // store, for example S014
     articleCode: string;  // article (product), for example A1001
     name: string;
     qty: number;
     priceCents: number;   // integer cents, never floating-point dollars
   }
   
   export type Lookup =
     | { ok: true; row: StockRow }
     | { ok: false; status: 400 | 404; error: string };
   
   const bySiteAndArticle = new Map<string, StockRow>(
     rows.map((r: StockRow) => [`${r.siteId}:${r.articleCode}`, r]),
   );
   
   const SITE_ID = /^S\d{3}$/;
   const ARTICLE_CODE = /^A\d{4,8}$/;
   
   export function lookup(siteId: string | null, articleCode: string | null): Lookup {
     if (!siteId || !SITE_ID.test(siteId)) {
       return { ok: false, status: 400, error: 'siteId must look like S014' };
     }
     if (!articleCode || !ARTICLE_CODE.test(articleCode)) {
       return { ok: false, status: 400, error: 'articleCode must look like A1001' };
     }
     const row = bySiteAndArticle.get(`${siteId}:${articleCode}`);
     return row ? { ok: true, row } : { ok: false, status: 404, error: 'no stock record' };
   }

   src/data/stock.json holds five rows such as {"siteId": "S014", "articleCode": "A1001", "name": "Basmati rice 5 kg", "qty": 42, "priceCents": 850}. Commit with a Conventional Commit message:

   TerminalCopy

   npm test
   git add -A && git commit -m "feat(api): look up stock by siteId and articleCode"

6. Serve it over HTTP, with a test that uses a real port

   The server knows about requests and responses, not stock rules. Configuration comes from environment variables, so the same code runs on a laptop and in the container. The test starts the server on port 0, which means "any free port", so tests never clash.

   src/server.tssrc/main.tstest/server.test.ts

   TypeScriptCopy

   // src/server.ts: HTTP routes. Knows about requests and responses, not about stock rules.
   import http from 'node:http';
   import { lookup } from './stock.ts';
   
   export interface ServerOptions {
     allowedOrigin: string;   // the page's origin, for CORS
     version: string;         // shown by /health so we can check what is deployed
   }
   
   export function createServer({ allowedOrigin, version }: ServerOptions): http.Server {
     return http.createServer((req, res) => {
       const url = new URL(req.url ?? '/', 'http://localhost');
       res.setHeader('access-control-allow-origin', allowedOrigin);
   
       if (req.method === 'GET' && url.pathname === '/health') {
         return send(res, 200, { ok: true, version });
       }
       if (req.method === 'GET' && url.pathname === '/api/stock') {
         const result = lookup(url.searchParams.get('siteId'), url.searchParams.get('articleCode'));
         return result.ok ? send(res, 200, result.row) : send(res, result.status, { error: result.error });
       }
       send(res, 404, { error: 'not found' });
     });
   }
   
   function send(res: http.ServerResponse, status: number, body: unknown): void {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(body));
   }

   TerminalCopy

   npm start
   # in a second terminal:
   curl -s 'localhost:3000/api/stock?siteId=S014&articleCode=A1001' -w '  (HTTP %{http_code})\n'
   curl -s 'localhost:3000/api/stock?siteId=S020&articleCode=A2040' -w '  (HTTP %{http_code})\n'
   curl -s 'localhost:3000/api/stock?siteId=Downtown&articleCode=A1001' -w '  (HTTP %{http_code})\n'
   curl -s 'localhost:3000/health' -w '  (HTTP %{http_code})\n'

   OutputCopy

   stock API dev on port 3000, allowing http://localhost:8080
   {"siteId":"S014","articleCode":"A1001","name":"Basmati rice 5 kg","qty":42,"priceCents":850}  (HTTP 200)
   {"error":"no stock record"}  (HTTP 404)
   {"error":"siteId must look like S014"}  (HTTP 400)
   {"ok":true,"version":"dev"}  (HTTP 200)

   TerminalCopy

   git add -A && git commit -m "feat(api): serve GET /api/stock and /health over HTTP"

7. Add the page and open the PR

   The page is plain HTML with a form. web/config.js holds the API address; the release workflow overwrites it for production. The first version of app.js is the "happy path" only, which is what a reviewer will catch.

   web/app.js (first version)web/config.js

   JavaScriptCopy

   // web/app.js: read the form, call the API, show the answer as text (never innerHTML)
   import { API_BASE } from './config.js';
   
   const form = document.querySelector('#lookup');
   const result = document.querySelector('#result');
   const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
   
   form.addEventListener('submit', async (event) => {
     event.preventDefault();
     const params = new URLSearchParams(new FormData(form));
     const res = await fetch(`${API_BASE}/api/stock?${params}`);
     const body = await res.json();
     result.textContent = `${body.name}: ${body.qty} in stock at ${body.siteId}, ${money.format(body.priceCents / 100)}`;
   });

   Serve web/ with any static server, for example npx serve web -l 8080, and try it. Then commit, push and open the PR. Closes #1 in the body links the PR to the issue and closes it on merge.

   TerminalCopy

   git add -A && git commit -m "feat(web): stock lookup page"
   git push -u origin feat/1-stock-api
   gh pr create --base main --title "feat: stock lookup API and page" \
     --body "Closes #1
   
   What: GET /api/stock and /health, plus a page that calls it.
   How to test: npm start, npx serve web -l 8080, try S014 / A1001.
   Risk: low; new code only."

   On GitHub: PR #3 opens, linked to issue #1, and CI runs both matrix jobs. Locally, the same checks pass:

   TerminalCopy

   npm run lint; npm run typecheck; npm test -- --test-reporter=tap

   OutputCopy

   > store-stock-checker@0.0.0 lint
   > eslint .
   
   > store-stock-checker@0.0.0 typecheck
   > tsc --noEmit
   
   > store-stock-checker@0.0.0 test
   > node --test --test-reporter=tap
   
   ok 1 - GET /api/stock returns the row as JSON with a CORS header
   ok 2 - GET /health reports the version
   ok 3 - finds stock for a known store and article
   ok 4 - returns 404 when the store does not stock the article
   ok 5 - rejects badly formed input with 400
   1..5
   # tests 5
   # pass 5
   # fail 0

8. Respond to review

   The reviewer runs the page, turns off Wi-Fi, and looks up a pair that does not exist. For the 404 the page shows undefined: undefined in stock at undefined, $NaN, and when the network is down or very slow it shows nothing at all. Store Wi-Fi is often flaky, so they request changes (on GitHub):

   TerminalCopy

   gh pr review 3 --request-changes --body "Please handle errors: a 404 shows 'undefined', and with no network the page hangs. Add a timeout."

   You fix it on the same branch. The diff shows exactly what changed, which makes the second review fast:

   DiffCopy

   @@ -8,7 +8,16 @@ const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD
    form.addEventListener('submit', async (event) => {
      event.preventDefault();
      const params = new URLSearchParams(new FormData(form));
   -  const res = await fetch(`${API_BASE}/api/stock?${params}`);
   -  const body = await res.json();
   -  result.textContent = `${body.name}: ${body.qty} in stock at ${body.siteId}, ${money.format(body.priceCents / 100)}`;
   +  result.className = '';
   +  result.textContent = 'Checking...';
   +  try {
   +    const res = await fetch(`${API_BASE}/api/stock?${params}`, { signal: AbortSignal.timeout(5000) });
   +    const body = await res.json();
   +    if (!res.ok) throw new Error(body.error);
   +    result.className = body.qty === 0 ? 'out' : '';
   +    result.textContent = `${body.name}: ${body.qty} in stock at ${body.siteId}, ${money.format(body.priceCents / 100)}`;
   +  } catch (err) {
   +    result.className = 'out';
   +    result.textContent = `Could not check stock: ${err.message}`;   // network down, timeout, 404
   +  }
    });

   TerminalCopy

   git commit -am "fix(web): show errors and time out after 5 seconds"
   git push
   git log --oneline main..HEAD

   OutputCopy

   73ec384 fix(web): show errors and time out after 5 seconds
   7b314c3 feat(web): stock lookup page
   8c3bbcb feat(api): serve GET /api/stock and /health over HTTP
   d1bc459 feat(api): look up stock by siteId and articleCode

   We ran the page's code against the running API (in Node, with the two page elements stubbed), looking up three pairs:

   OutputCopy

   S014 A1001 -> Basmati rice 5 kg: 42 in stock at S014, $8.50
   S014 A1002 -> Sunflower oil 2 L: 0 in stock at S014, $7.40
   S020 A2040 -> Could not check stock: no stock record

   On GitHub: the reviewer approves (gh pr review 3 --approve), CI is green on the new commit, and you squash-merge. The four branch commits become one commit on main, and issue #1 closes.

   TerminalCopy

   gh pr merge 3 --squash --delete-branch
   git switch main && git pull
   git log --oneline

   OutputCopy

   c8c16bd (HEAD -> main, origin/main) feat: stock lookup API and page (#3)
   2b5e9bd ci: lint, type check and test on Node 22 and 24 (#2)
   c81b7e9 chore: scaffold project with TypeScript, ESLint and README

9. Add the release workflow and the Dockerfile

   One workflow, triggered only by a version tag, with three jobs. check runs the same checks again. If they pass, page and image run in parallel. Each job gets only the permissions it needs. The two official GitHub Pages actions are used at their current major versions; the three third-party Docker actions are pinned to full commit SHAs with the version in a comment, as Deploying and securing with GitHub Actions recommends.

   release.yml (check, page)release.yml (image)Dockerfile

   YAMLCopy

   # .github/workflows/release.yml: on a version tag, ship the page and the API image
   name: Release
   on:
     push:
       tags: ['v*.*.*']
   
   permissions:
     contents: read
   
   jobs:
     check:                                  # never ship a tag that fails the checks
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with: { node-version: 24, cache: npm }
         - run: npm ci
         - run: npm run check
   
     page:
       needs: check
       runs-on: ubuntu-latest
       permissions:
         contents: read                      # job-level permissions replace the defaults
         pages: write                        # deploy to Pages
         id-token: write                     # prove the deploy comes from this workflow
       environment:
         name: github-pages
         url: ${{ steps.deploy.outputs.page_url }}
       steps:
         - uses: actions/checkout@v7
         - name: Point the page at the production API
           env:
             API_BASE_URL: ${{ vars.API_BASE_URL }}   # a repository variable, set once
           run: |
             mkdir _site && cp web/* _site/
             echo "export const API_BASE = '$API_BASE_URL';" > _site/config.js
         - uses: actions/upload-pages-artifact@v5
           with: { path: _site }
         - id: deploy
           uses: actions/deploy-pages@v5

   The API_BASE_URL value goes through an env: entry instead of being pasted into the script. That is a habit worth keeping: values from ${{ }} expressions placed directly in a run: script can inject shell code if they ever contain user input. The .dockerignore file keeps node_modules, tests, the page and .git out of the image.

   We could not run Docker from here, so we checked the image's contents another way: copy exactly what the Dockerfile copies into an empty folder, run the same install, and start it the same way on Node 24.

   TerminalCopy

   NODE_ENV=production npm ci --omit=dev --ignore-scripts
   NODE_ENV=production APP_VERSION=v1.0.0 PORT=3100 node src/main.ts
   curl -s localhost:3100/health

   OutputCopy

   found 0 vulnerabilities
   stock API v1.0.0 on port 3100, allowing http://localhost:8080
   {"ok":true,"version":"v1.0.0"}

10. Configure Pages and the production API address (on GitHub)

    Tell GitHub that Pages is published by a workflow, set the API address as a repository variable, and allow tags to deploy to the github-pages environment. By default that environment accepts only the default branch, so a tag-triggered deploy fails with "is not allowed to deploy to github-pages due to environment protection rules" until you add a tag rule.

    TerminalCopy

    gh api repos/{owner}/{repo}/pages --method POST -f build_type=workflow
    gh variable set API_BASE_URL --body "https://stock-api.example.com"
    gh api repos/{owner}/{repo}/environments/github-pages --method PUT --input - <<'EOF'
    {"deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}}
    EOF
    gh api repos/{owner}/{repo}/environments/github-pages/deployment-branch-policies --method POST -f name=main -f type=branch
    gh api repos/{owner}/{repo}/environments/github-pages/deployment-branch-policies --method POST -f 'name=v*.*.*' -f type=tag

    If the environment already has a rule for main, GitHub refuses the duplicate; you can ignore that error.

    In the web interface, the same settings live under Settings: Pages (Source: GitHub Actions), Secrets and variables, Actions (Variables tab), and Environments, github-pages (Deployment branches and tags). The API address must be a real HTTPS host that runs the image; see the next step.

11. Cut v1.0.0

    Write the changelog entry and bump the version in the same PR as the release workflow (#4), merge it like any other change, then tag main. An annotated tag (-a) records who tagged it, when, and a message (Branching strategies, releases and versions).

    MarkdownCopy

    # Changelog
    
    All notable changes to this project. Versions follow semantic versioning.
    
    ## [1.0.0] - 2026-10-07
    
    ### Added
    - `GET /api/stock?siteId=&articleCode=` returns name, quantity and price in cents (#3)
    - `GET /health` reports the deployed version
    - Stock lookup page with error states and a 5 second timeout (#3)
    - CI on Node 22 and 24; release workflow for GitHub Pages and GHCR (#2, #4)

    TerminalCopy

    npm version 1.0.0 --no-git-tag-version   # updates package.json and the lockfile only
    # ...commit, PR #4, review, squash-merge, then on main:
    git switch main && git pull
    git tag -a v1.0.0 -m "v1.0.0: first release of store-stock-checker"
    git push origin v1.0.0
    gh release create v1.0.0 --verify-tag --generate-notes

    On GitHub: the tag push starts the Release workflow. Watch it with gh run watch. Expect check, then page and image side by side, in a few minutes in total. The run summary shows the site address, which for a project repo is https://YOUR-USER.github.io/store-stock-checker/. The image job pushes ghcr.io/your-user/store-stock-checker:1.0.0 and :latest (image names are lowercased). gh release create --generate-notes builds release notes from the merged PRs since the last tag.

12. Run the API image on a server

    The page is static, so GitHub Pages can host it. The API needs a machine. On any Linux server with Docker, or a container service such as Cloud Run, Azure Container Apps or a VPS, run the image. A new package on GHCR is private by default, so log in with a token that has the read:packages scope, or make the package public in its settings.

    TerminalCopy

    echo "$CR_PAT" | docker login ghcr.io -u YOUR-USER --password-stdin
    docker run -d --name stock-api --restart unless-stopped -p 3000:3000 \
      -e ALLOWED_ORIGIN=https://YOUR-USER.github.io \
      ghcr.io/your-user/store-stock-checker:1.0.0
    curl -s localhost:3000/health

    Expected: {"ok":true,"version":"v1.0.0"}. Put HTTPS in front (a reverse proxy such as Caddy or nginx, or the platform's own), because a page served over HTTPS cannot call an http:// API. Automating this step from the workflow over SSH or OIDC is covered in Deploying and securing with GitHub Actions; doing it by hand once first is how you learn what to automate.

13. The next morning: a bug report, a failing test, a hotfix

    Issue #5 arrives: "New article A100000123 (brown bread) returns an error." The cause is the article code pattern, which allows 4 to 8 digits. The rule is test first: write a test that reproduces the report and watch it fail. That proves you found the real cause, and it stops the bug coming back.

    TerminalCopy

    git switch main && git pull
    git switch -c fix/5-long-article-codes

    TypeScriptCopy

    test('accepts the new 9-digit article codes (issue #5)', () => {
      const r = lookup('S014', 'A100000123');
      assert.ok(r.ok, 'expected a stock row, got an error');
      assert.equal(r.row.name, 'Brown bread 350 g');
    });

    TerminalCopy

    npm test -- --test-reporter=tap

    OutputCopy

    ok 1 - GET /api/stock returns the row as JSON with a CORS header
    ok 2 - GET /health reports the version
    ok 3 - finds stock for a known store and article
    ok 4 - returns 404 when the store does not stock the article
    ok 5 - rejects badly formed input with 400
    not ok 6 - accepts the new 9-digit article codes (issue \#5)
      ---
      location: '.../store-stock-checker/test/stock.test.ts:22:1'
      failureType: 'testCodeFailure'
      error: 'expected a stock row, got an error'
      code: 'ERR_ASSERTION'
      name: 'AssertionError'
      expected: true
      actual: false
      operator: '=='
      ...
    1..6
    # tests 6
    # pass 5
    # fail 1

    The fix is one character, plus the same change in the page's pattern attribute:

    DiffCopy

    @@ -18,7 +18,7 @@ const bySiteAndArticle = new Map<string, StockRow>(
     );
     
     const SITE_ID = /^S\d{3}$/;
    -const ARTICLE_CODE = /^A\d{4,8}$/;
    +const ARTICLE_CODE = /^A\d{4,9}$/;   // new articles have 9 digits (issue #5)
     
     export function lookup(siteId: string | null, articleCode: string | null): Lookup {
       if (!siteId || !SITE_ID.test(siteId)) {

    OutputCopy

    ok 6 - accepts the new 9-digit article codes (issue \#5)
    # tests 6
    # pass 6
    # fail 0

    Add a 1.0.1 section to the changelog ("Fixed: accept 9-digit article codes such as A100000123; they returned 400 (#5)"), bump the patch version with npm version patch --no-git-tag-version, open PR #6 with Closes #5, get it approved and merged, then tag. A bug fix with no new features is a patch release (Node.js and npm explains semantic versioning).

    TerminalCopy

    git tag -a v1.0.1 -m "v1.0.1: accept 9-digit article codes"
    git push origin v1.0.1
    gh release create v1.0.1 --verify-tag --generate-notes
    git log --oneline --decorate

    OutputCopy

    539c556 (HEAD -> main, tag: v1.0.1, origin/main) fix(api): accept 9-digit article codes (#6)
    47672d0 (tag: v1.0.0) ci: deploy page to Pages and API image to GHCR on tags (#4)
    c8c16bd feat: stock lookup API and page (#3)
    2b5e9bd ci: lint, type check and test on Node 22 and 24 (#2)
    c81b7e9 chore: scaffold project with TypeScript, ESLint and README

    Five commits on main, each one a reviewed PR except the scaffold, and two tags that say exactly what is live. If v1.0.1 had a problem, rolling back is docker run with the 1.0.0 image, and re-running the v1.0.0 release workflow for the page.