@wirecat/cli-template 0.0.0-stage → 0.1.1

package/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  # Actions are pinned by commit; this is what moves the pins forward.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  # The shared packages, at most a day after they ship, so `new` always copies a template on the latest ones.
+  - package-ecosystem: npm
+    directory: /
+    # Looks redundant, but it is what keeps `allow` off security updates: with target-branch set,
+    # GitHub stops applying this entry's options to them, so every vulnerable package gets a PR.
+    target-branch: main
+    schedule:
+      interval: daily
+    allow:
+      - dependency-name: "@wirecat/*"
+    groups:
+      shared:
+        patterns:
+          - "@wirecat/*"
+    commit-message:
+      prefix: "chore(deps)"

package/.github/workflows/changelog-guard.yml

@@ -0,0 +1,12 @@
+name: Changelog guard
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    uses: WireCatLabs/cli-base/.github/workflows/changelog-guard.yml@70449547973dd113806a6829f4591dce713b5b78 # v0.51.1

package/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: Full validation
+
+on:
+  workflow_call:
+    inputs:
+      pack:
+        type: boolean
+        default: false
+      platforms:
+        type: boolean
+        default: false
+    outputs:
+      package-sha256:
+        value: ${{ jobs.ci.outputs.package-sha256 }}
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@70449547973dd113806a6829f4591dce713b5b78 # v0.51.1
+    with:
+      pack: ${{ inputs.pack || false }}
+      bun-run: pnpm build && pnpm smoke:bun
+      cli: true
+      bin: app
+      platforms: ${{ inputs.pack || inputs.platforms || github.event_name == 'workflow_dispatch' }}
+      platform-run: |
+        node dist/bin/app.js commands --json >/dev/null
+        node dist/bin/app.js doctor --json >/dev/null
+      # No version is on npm before the first release, so there is no earlier package to upgrade from.
+      skip: |
+        contracts:upgrade
+      checks: |
+        bash scripts/audit.sh
+
+  version:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+      # A warning, never a failure: a version npm already has is refused by bin/release, not here.
+      - name: version above main and npm
+        continue-on-error: true
+        run: |
+          pr=$(node -p 'require("./package.json").version')
+          git fetch -q --depth=1 origin main
+          main=$(git show FETCH_HEAD:package.json | node -p 'JSON.parse(require("fs").readFileSync(0)).version')
+          [ "$pr" != "$main" ] || exit 0
+          name=$(node -p 'require("./package.json").name')
+          latest=$(npm view "$name" version 2>/dev/null || true)
+          versions=$(npm view "$name" versions --json 2>/dev/null) || versions=""
+          next=$(pnpm exec cli-dev next-version "$pr" "$latest" "$versions")
+          [ "$next" != "$pr" ] || exit 0
+          echo "::warning file=package.json::version $pr is not above npm's latest ($latest); the next free one is $next"
+
+  prose:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: install vale
+        env:
+          VALE_VERSION: 3.23.0
+          VALE_SHA256: cc35445a45186b8f0b01e11c01359694cf941e72cf6ab0fc44774f0e54c9d5fc
+        run: |
+          curl -sSfLo vale.tar.gz "https://github.com/vale-cli/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
+          echo "${VALE_SHA256}  vale.tar.gz" | sha256sum -c -
+          tar -xzf vale.tar.gz vale
+      # Style findings are annotations until the rules are tuned; the tone rule (an error) fails.
+      - run: ./vale --output line README.md docs/*.md | sed 's/^/::warning::/' || true
+      - run: ./vale --minAlertLevel error README.md docs/*.md

package/.github/workflows/main.yml

@@ -0,0 +1,17 @@
+name: Main validation
+
+# Nothing here publishes or tags: release.yml alone does that.
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: main-validation-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validation:
+    uses: ./.github/workflows/ci.yml

package/.github/workflows/monthly.yml

@@ -0,0 +1,28 @@
+name: Monthly validation
+
+on:
+  schedule:
+    - cron: "41 3 1 * *"
+  workflow_dispatch:
+
+concurrency:
+  group: monthly-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  validation:
+    uses: ./.github/workflows/ci.yml
+    with:
+      platforms: true
+  security:
+    permissions:
+      contents: read
+      actions: read
+      security-events: write
+    uses: WireCatLabs/cli-base/.github/workflows/release-checks.yml@70449547973dd113806a6829f4591dce713b5b78 # v0.51.1
+    with:
+      dependencies: true
+      languages: '["actions","javascript-typescript"]'

package/.github/workflows/pr.yml

@@ -0,0 +1,19 @@
+name: PR validation
+
+# The whole Linux validation main.yml runs, on every pull request, so a change that breaks the coverage floor or a
+# check fails here and never reaches main (WC-CI-5).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: pr-validation-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  validation:
+    permissions:
+      contents: read
+    uses: ./.github/workflows/ci.yml

package/.github/workflows/release.yml

@@ -0,0 +1,191 @@
+name: Release
+
+# Started by bin/release. npm trusts this file by name (trusted publishing), so there is no npm
+# token anywhere in this repository and renaming the file breaks publishing until npm is told.
+#
+# Full validation builds, checks and packs once; `build` verifies the immutable tarball.
+# The job able to publish runs no code from our dependencies; `publish` holds the OIDC permission and only
+# runs `npm publish` on that file; `tag` is the only one that may write to the repository.
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build and pack, run npm publish --dry-run, do not tag"
+        type: boolean
+        default: false
+      commit:
+        description: "The commit bin/release checked; the run refuses any other"
+        type: string
+        default: ""
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  # Every job builds github.sha, the tip of main when the run started — which a merge can move past the commit
+  # bin/release checked.
+  checked-commit:
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - env:
+          COMMIT: ${{ inputs.commit }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          [ "$COMMIT" = "$GITHUB_SHA" ] && exit 0
+          [ "$DRY_RUN" = "true" ] && [ -z "$COMMIT" ] && exit 0
+          echo "::error::this run is at $GITHUB_SHA, but bin/release checked '${COMMIT}' — nothing is published"
+          exit 1
+
+  validation:
+    needs: checked-commit
+    if: github.ref == 'refs/heads/main' || inputs.dry_run
+    permissions:
+      contents: read
+    uses: ./.github/workflows/ci.yml
+    with:
+      pack: true
+
+  checks:
+    needs: checked-commit
+    if: github.ref == 'refs/heads/main' || inputs.dry_run
+    permissions:
+      contents: read
+      actions: read
+      security-events: write
+    uses: WireCatLabs/cli-base/.github/workflows/release-checks.yml@70449547973dd113806a6829f4591dce713b5b78 # v0.51.1
+
+  build:
+    needs: [checks, validation]
+    if: github.ref == 'refs/heads/main' || inputs.dry_run
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      name: ${{ steps.version.outputs.name }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          package-manager-cache: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: validated-package
+          path: validated
+      - name: Verify validated package integrity
+        env:
+          EXPECTED_SHA256: ${{ needs.validation.outputs.package-sha256 }}
+        run: |
+          set -- ./validated/*.tgz
+          [ "$#" -eq 1 ] && [ -f "$1" ] || { echo "Expected exactly one package tarball"; exit 1; }
+          [ -n "$EXPECTED_SHA256" ] || { echo "Missing validation digest"; exit 1; }
+          printf '%s  %s\n' "$EXPECTED_SHA256" "$1" | sha256sum --check -
+
+      # A 404 for a package npm has never seen means "not published yet", the same as a missing version.
+      - name: version not yet on npm
+        id: version
+        env:
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          version=$(node -p 'require("./package.json").version')
+          name=$(node -p 'require("./package.json").name')
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "name=$name" >> "$GITHUB_OUTPUT"
+          if [ "$DRY_RUN" != "true" ] && npm view "$name@$version" version --prefer-online >/dev/null 2>&1; then
+            echo "::error::$version is already on npm — raise the version first"
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: package
+          path: validated/*.tgz
+          if-no-files-found: error
+          retention-days: 7
+
+  package-dry-run:
+    needs: build
+    if: inputs.dry_run
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          package-manager-cache: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: package
+      # Permit checking an already published version; this job has no publishing permissions.
+      - run: npm publish ./*.tgz --access public --dry-run --force
+
+  publish:
+    needs: build
+    if: ${{ !inputs.dry_run }}
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      id-token: write
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      NAME: ${{ needs.build.outputs.name }}
+    steps:
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: package
+
+      # npm, not pnpm: npm's trusted publishing is the documented path. A tarball runs no
+      # lifecycle scripts, and nothing is installed here. A tarball path needs its ./.
+      - run: |
+          set -- ./*.tgz
+          npm publish "$1" --access public
+
+      - name: wait for npm to show the version
+        run: |
+          # The version's own document, not `npm view`: on 2026-10-01 the document answered while the
+          # version list `npm view` reads was still stale for minutes.
+          encoded=$(node -p 'encodeURIComponent(process.argv[1]).replace("%40", "@")' "$NAME")
+          for _ in $(seq 90); do
+            curl -sfo /dev/null "https://registry.npmjs.org/$encoded/$VERSION" && exit 0
+            sleep 10
+          done
+          echo "::error::npm does not show $VERSION after fifteen minutes — not tagging; tag v$VERSION by hand once it does"
+          exit 1
+
+  tag:
+    needs: [build, publish]
+    if: ${{ !inputs.dry_run }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "$VERSION"
+          git push origin "v$VERSION"
+
+      - name: GitHub release from the changelog
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          awk -v v="$VERSION" '$0 ~ "^## "v" " {on=1; next} /^## / && on {exit} on' CHANGELOG.md |
+            gh release create "v$VERSION" --title "$VERSION" --notes-file -

package/.github/workflows/standards.yml

@@ -0,0 +1,51 @@
+name: Shared standards
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: fast-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  standards:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+      - run: pnpm standards:check
+      - run: pnpm lint
+      - run: pnpm docs:lint
+      - name: Early bug checks
+        timeout-minutes: 2
+        run: pnpm run --if-present ci:quick
+      - name: Scan new commits for secrets
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+          GITLEAKS_VERSION: 8.30.1
+          GITLEAKS_SHA256: 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+        run: |
+          curl -sSfLo gitleaks.tar.gz "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          echo "${GITLEAKS_SHA256}  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz gitleaks
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            range="$HEAD_SHA^!"
+          else
+            range="$BASE_SHA..$HEAD_SHA"
+          fi
+          ./gitleaks git --log-opts="$range" --no-banner --redact --exit-code 1 .

package/.gitleaks.toml

@@ -0,0 +1,5 @@
+[extend]
+useDefault = true
+
+[allowlist]
+paths = ['''pnpm-lock\.yaml''']

package/.markdownlint-cli2.jsonc

@@ -0,0 +1,7 @@
+{
+  "globs": ["README.md", "SECURITY.md", "AGENTS.md", "CLAUDE.md", "docs/*.md", "docs/dev/**/*.md", "skills/**/*.md"],
+  "ignores": ["node_modules", "dist", ".worktrees", "config/wirecat", "docs/commands.md", "docs/dev/test-matrix.md"],
+  "config": {
+    "extends": "./config/wirecat/markdownlint.json"
+  }
+}

package/.vale.ini

@@ -0,0 +1,5 @@
+StylesPath = node_modules/@wirecat/cli-base/config/vale
+MinAlertLevel = warning
+
+[*.md]
+BasedOnStyles = CliDocs

package/AGENTS.md

@@ -0,0 +1,27 @@
+# Working rules for agents
+
+The [WireCat CLI standards](node_modules/@wirecat/cli-base/docs/standards/README.md) apply here and win over this
+file and over every other document in this repository. The handbook ships inside `@wirecat/cli-base`; run
+`pnpm install` first. Read the page for the area you change before changing it, and cite the rule ids the change
+touches (`WC-<AREA>-<n>`) in the commit message and the pull request. The rules of this CLI alone are in
+[CLAUDE.md](CLAUDE.md).
+
+## Before building anything
+
+This CLI was made from [cli-template](https://github.com/WireCatLabs/cli-template). Its first task is the design:
+
+1. Read [docs/dev/DESIGN.md](docs/dev/DESIGN.md). If the seven answers are not there, ask the owner the
+   [design interview](docs/dev/skills/design-interview/SKILL.md) and write them down.
+2. Learn from the reference CLI below. Copy its patterns for the provider, the store and the commands; the
+   template has no sample code on purpose.
+3. Ask the further questions in the interview that the reference CLI does not answer. Build only after the owner
+   has read `DESIGN.md`.
+
+<!-- cli-template:reference-cli:start -->
+The reference CLI is not chosen yet; see [Reference CLIs](docs/dev/reference-clis.md).
+<!-- cli-template:reference-cli:end -->
+
+## Template-owned files
+
+`template.json` names the files `npx @wirecat/cli-template upgrade` keeps in step with the template. Change one of
+them here only when this CLI needs to differ; `upgrade` asks before it touches your change.

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+Notable changes to `@wirecat/cli-template`. One section per version, newest first; versions follow
+[semantic versioning](https://semver.org), so before `1.0.0` the skeleton may still change.
+
+## 0.1.1 — 25.10.2026
+
+### Fixed
+
+- **`npx @wirecat/cli-template new` works.** It stopped with `template.json lists ".gitignore", but the package has
+  no such file`, because npm renames `.gitignore` when it installs a package. The package now ships the file under
+  another name, and `new` and `upgrade` write it as `.gitignore`.
+- **`new` and `upgrade` work on Windows.** `new` now marks `bin/release` and the other scripts as executable in
+  git, so a CLI made on Windows can still run them on Linux and macOS. `upgrade` no longer reads every file as
+  edited when git checked it out with Windows line endings, and it downloads the earlier template version without
+  needing a shell for `npm`.
+
+## 0.1.0 — 25.10.2026
+
+### Added
+
+- **A working skeleton for a new WireCat CLI.** The shared root commands `commands`, `doctor`, `skill`, `mcp` and
+  `upgrade`, and `config`, on cli-base and cli-core. Every example names its profile; the MCP server offers every
+  command, writes included, and the profile's permissions decide what runs.
+- **The checks of the WireCat standards, from the first commit.** CI runs lint, the type check, tests with coverage,
+  the command lint and audit, the contracts, the test matrix, the docs checks and the changelog guard.
+- **`npx @wirecat/cli-template new` and `upgrade`.** `new` copies the template into a new folder, renames it, asks
+  the seven design questions (or takes them as flags) and prints the four steps that need a person. `upgrade` brings
+  later template changes into a CLI made from it, file by file: apply, replace, skip or diff.
+- **A design interview for the agent that builds the new CLI**, and a page that names the CLI to learn from for each
+  kind of tool.

package/CLAUDE.md

@@ -0,0 +1,17 @@
+# app — working rules
+
+The [WireCat CLI standards](node_modules/@wirecat/cli-base/docs/standards/README.md) apply here and win over this
+file; it keeps only the rules of `app` itself. Start with [AGENTS.md](AGENTS.md).
+
+**What cli-core already does, this repository does not do again** — commands, the store, search, MCP and the
+permissions. A gap in cli-core is fixed in cli-core.
+
+## Local rules
+
+None yet. Add a rule here only when it holds for `app` alone, and link the handbook rule it narrows.
+
+## Private working folder
+
+Plans, research and journals do not go into this repository. For WireCat's own CLIs they live in the private
+repository `WireCatLabs/cli-private`, linked or cloned into `docs_ai/`, which git ignores. Elsewhere, keep them in a
+folder of your own outside the repository.