diff --git a/.github/workflows/ackit-action-dogfood.yml b/.github/workflows/ackit-action-dogfood.yml index 6f859bb0..09c83033 100644 --- a/.github/workflows/ackit-action-dogfood.yml +++ b/.github/workflows/ackit-action-dogfood.yml @@ -16,22 +16,20 @@ jobs: steps: # actions/checkout@v4 (f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a) - uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a - # actions/setup-node@v4 (ae0d4ed08881f17d1511386f5be3e62356acd4a6) - - uses: actions/setup-node@ae0d4ed08881f17d1511386f5be3e62356acd4a6 - with: - node-version: "24" - # pnpm/action-setup@v4 (b906affcce14559ad1aafd4ab0e942779e9f58b1) - - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 - with: - package_json_file: package.json - - run: pnpm install --frozen-lockfile - - run: pnpm build - name: Run ACKit via local action (scan) + id: ackit uses: ./ with: command: scan args: "--json" - fail-threshold: low - upload-sarif: "false" + fail-threshold: medium + upload-sarif: "true" - name: Verify findings JSON exists - run: test -f "${RUNNER_TEMP}/ackit-findings.json" && echo "findings JSON present" && cat "${RUNNER_TEMP}/ackit-findings.json" | head -20 + env: + FINDINGS: ${{ steps.ackit.outputs.findings-json }} + SARIF: ${{ steps.ackit.outputs.sarif-path }} + run: | + test -f "${FINDINGS}" + test -f "${SARIF}" + - name: Clean external Action consumer + run: pnpm run smoke:action diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b8a5f76c..dfac7e86 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,6 +41,14 @@ jobs: run: pnpm typecheck - name: Build run: pnpm build + - name: Schema drift + run: | + pnpm gen:schemas + git diff --exit-code -- schemas + - name: CLI smoke + run: pnpm smoke:cli + - name: Version parity + run: node scripts/check-version-parity.mjs - name: Offline-egress static gate run: node scripts/check-offline-egress.mjs - name: Text hygiene (C0 controls) @@ -107,7 +115,8 @@ jobs: run: | node -e " const pkg=require('./extensions/vscode/package.json'); - if(pkg.version!=='0.5.4') throw new Error('extension version must be 0.5.4'); + const root=require('./package.json'); + if(pkg.version!==root.version) throw new Error('extension/root version mismatch'); if(pkg.publisher!=='Cynrath') throw new Error('publisher must be Cynrath'); if(pkg.displayName!=='ACKit Toolkit') throw new Error('displayName must be ACKit Toolkit'); if(!pkg.contributes.views.ackit.find(v=>v.id==='ackit.readiness')) throw new Error('ackit.readiness view missing'); @@ -116,85 +125,31 @@ jobs: console.log('manifest contract PASS'); " - name: Extension typecheck - run: | - pnpm --filter ackit-vscode exec tsc -p tsconfig.json --noEmit - pnpm --filter ackit-vscode exec tsc -p tsconfig.test.json --noEmit + run: pnpm --filter ackit-vscode run typecheck - name: Extension lint (vscode src) - run: | - pnpm --filter ackit-vscode exec biome check src --diagnostic-level=warn || true + run: pnpm --filter ackit-vscode run lint - name: Extension build run: | - pnpm --filter ackit-vscode exec esbuild src/extension.ts --bundle --platform=node --target=node20 --outfile=dist/extension.js --external:vscode --sourcemap + pnpm --filter ackit-vscode run build test -f extensions/vscode/dist/extension.js - name: Extension unit tests - run: | - pnpm --filter ackit-vscode run compile:test - # run mocha unit tests directly (without Electron) if available - pnpm --filter ackit-vscode exec mocha out/test/suite/unit.test.js --timeout 5000 || echo "unit tests done" + run: pnpm --filter ackit-vscode run test:unit - name: VS Code Electron integration (xvfb) - run: | - pnpm --filter ackit-vscode run compile:test - xvfb-run -a pnpm --filter ackit-vscode test || echo "Electron integration completed (check logs)" + run: xvfb-run -a pnpm --filter ackit-vscode test + - name: Version parity + run: node scripts/check-version-parity.mjs - name: vsce ls run: | cd extensions/vscode - npx --yes @vscode/vsce ls --no-dependencies --no-yarn + npx --yes @vscode/vsce@4.1.1 ls --no-dependencies --no-yarn - name: vsce package --no-dependencies run: | - cd extensions/vscode - npx --yes @vscode/vsce package --no-dependencies --no-yarn --out ackit-vscode-0.5.4.vsix - test -f ackit-vscode-0.5.4.vsix - ls -lh ackit-vscode-0.5.4.vsix - - name: VSIX content audit - run: | - cd extensions/vscode - npx --yes @vscode/vsce ls --no-dependencies --no-yarn > /tmp/vsce-ls.txt - cat /tmp/vsce-ls.txt - if grep -q "node_modules" /tmp/vsce-ls.txt; then echo "::error::VSIX contains node_modules"; exit 1; fi - # check icon exists and size - ls -lh images/icon.png - file images/icon.png - # check VSIX size <2MB - size=$(stat -c%s ackit-vscode-0.5.4.vsix 2>/dev/null || stat -f%z ackit-vscode-0.5.4.vsix) - echo "VSIX size $size bytes" - if [ "$size" -gt 2097152 ]; then echo "::error::VSIX >2MB"; exit 1; fi - # check no secrets in VSIX - unzip -l ackit-vscode-0.5.4.vsix | head -20 - if unzip -p ackit-vscode-0.5.4.vsix extension/package.json | grep -q "AKIA"; then echo "::error::secret in VSIX"; exit 1; fi - - name: Packaged VSIX parity (Marketplace content) - run: | - cd extensions/vscode - pkgver=$(node -p "require('./package.json').version") + pkgver=$(node -p "require('./extensions/vscode/package.json').version") vsix="ackit-vscode-${pkgver}.vsix" - test -f "$vsix" - manver=$(unzip -p "$vsix" extension/package.json | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).version))") - if [ "$manver" != "$pkgver" ]; then echo "::error::VSIX manifest $manver != $pkgver"; exit 1; fi - unzip -p "$vsix" extension/readme.md > /tmp/vsix-readme.md - grep -q "\*\*Version:\*\* \`$pkgver\`" /tmp/vsix-readme.md || { echo "::error::VSIX README Version != $pkgver"; exit 1; } - grep -q "ackit.status.v1" /tmp/vsix-readme.md || { echo "::error::VSIX README missing ackit.status.v1"; exit 1; } - grep -qi "verification freshness" /tmp/vsix-readme.md || { echo "::error::VSIX README missing verification freshness"; exit 1; } - grep -qi "checkpoint freshness" /tmp/vsix-readme.md || { echo "::error::VSIX README missing checkpoint freshness"; exit 1; } - unzip -p "$vsix" extension/changelog.md > /tmp/vsix-changelog.md - latest=$(grep -m1 -o '^## \[[^]]*\]' /tmp/vsix-changelog.md) - echo "VSIX CHANGELOG latest: $latest" - echo "$latest" | grep -q "## \[$pkgver\]" || { echo "::error::VSIX CHANGELOG latest != $pkgver"; exit 1; } - echo "packaged VSIX parity PASS ($pkgver)" - - name: Icon dimensions - run: | cd extensions/vscode - node -e " - const fs=require('fs'); - const buf=fs.readFileSync('images/icon.png'); - const w=buf.readUInt32BE(16), h=buf.readUInt32BE(20); - console.log('icon',w+'x'+h, buf.length+' bytes'); - if(w<128||h<128) throw new Error('icon <128'); - if(w!==h) throw new Error('icon not square'); - if(w!==256) console.log('warning: icon not 256x256 but square and >=128, accepting'); - if(buf.length<=1024) throw new Error('icon too small'); - " + npx --yes @vscode/vsce@4.1.1 package --no-dependencies --no-yarn --out "${vsix}" + echo "VSIX_PATH=$(pwd)/${vsix}" >> "${GITHUB_ENV}" + - name: VSIX content audit and packaged parity + run: node scripts/check-vsix.mjs "${VSIX_PATH}" - name: Offline-egress extension audit - run: | - node scripts/check-offline-egress.mjs - # also ensure extension src has no fetch/http - if grep -R "fetch.*http" extensions/vscode/src; then echo "::error::extension fetch"; exit 1; fi - echo "offline-egress PASS" + run: node scripts/check-offline-egress.mjs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9aeb4368..04cd168c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -184,10 +184,10 @@ jobs: echo "::error::extension publisher '${EXT_PUB}' != 'Cynrath'" exit 52 fi - pnpm --filter ackit-vscode exec esbuild src/extension.ts --bundle --platform=node --target=node20 --outfile=dist/extension.js --external:vscode --sourcemap + pnpm --filter ackit-vscode run build test -f extensions/vscode/dist/extension.js cd extensions/vscode - npx --yes @vscode/vsce package --no-dependencies --no-yarn --out "ackit-vscode-${RELEASE_VERSION}.vsix" + npx --yes @vscode/vsce@4.1.1 package --no-dependencies --no-yarn --out "ackit-vscode-${RELEASE_VERSION}.vsix" test -f "ackit-vscode-${RELEASE_VERSION}.vsix" VSIX_ABS="$(pwd)/ackit-vscode-${RELEASE_VERSION}.vsix" VSIX_SHA256="$(sha256sum "${VSIX_ABS}" | cut -d' ' -f1)" @@ -250,7 +250,7 @@ jobs: exit 61 fi cd extensions/vscode - npx --yes @vscode/vsce ls --no-dependencies --no-yarn > /tmp/vsce-ls.txt + npx --yes @vscode/vsce@4.1.1 ls --no-dependencies --no-yarn > /tmp/vsce-ls.txt cat /tmp/vsce-ls.txt if grep -q "node_modules" /tmp/vsce-ls.txt; then echo "::error::vsce ls lists node_modules" @@ -267,6 +267,7 @@ jobs: echo "::error::secret pattern in VSIX manifest" exit 64 fi + node scripts/check-vsix.mjs "${VSIX_PATH}" node scripts/check-offline-egress.mjs if grep -R "fetch.*http" extensions/vscode/src; then echo "::error::extension source contains remote fetch" @@ -326,7 +327,7 @@ jobs: fi seen=0 for attempt in 1 2 3; do - if npx --yes @vscode/vsce show Cynrath.ackit-vscode --json > /tmp/mkt-pre.json 2> /tmp/mkt-pre.err; then + if npx --yes @vscode/vsce@4.1.1 show Cynrath.ackit-vscode --json > /tmp/mkt-pre.json 2> /tmp/mkt-pre.err; then PRE_VER="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-pre.json','utf8')).versions?.[0]?.version ?? 'unknown'")" echo "Marketplace live latest: ${PRE_VER} (release target ${RELEASE_VERSION})" if [ "${PRE_VER}" = "${RELEASE_VERSION}" ]; then @@ -425,7 +426,7 @@ jobs: set -euo pipefail seen=0 for attempt in $(seq 1 30); do - if npx --yes @vscode/vsce show Cynrath.ackit-vscode --json > /tmp/mkt-show.json 2> /tmp/mkt-show.err; then + if npx --yes @vscode/vsce@4.1.1 show Cynrath.ackit-vscode --json > /tmp/mkt-show.json 2> /tmp/mkt-show.err; then MKT_VER="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-show.json','utf8')).versions?.[0]?.version ?? ''")" if [ "${MKT_VER}" = "${RELEASE_VERSION}" ]; then seen=1 @@ -532,8 +533,17 @@ jobs: echo "::error::npm latest='${NPM_LATEST}' != '${RELEASE_VERSION}'" exit 90 fi - npx --yes @vscode/vsce show Cynrath.ackit-vscode --json > /tmp/mkt-final.json - MKT_FINAL="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-final.json','utf8')).versions?.[0]?.version ?? ''")" + MKT_FINAL="" + for attempt in $(seq 1 6); do + if npx --yes @vscode/vsce@4.1.1 show Cynrath.ackit-vscode --json > /tmp/mkt-final.json 2> /tmp/mkt-final.err; then + MKT_FINAL="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-final.json','utf8')).versions?.[0]?.version ?? ''")" + if [ "${MKT_FINAL}" = "${RELEASE_VERSION}" ]; then + break + fi + fi + echo "final Marketplace read attempt ${attempt}/6: stale or unreadable; target ${RELEASE_VERSION}" + if [ "${attempt}" -lt 6 ]; then sleep 10; fi + done if [ "${MKT_FINAL}" != "${RELEASE_VERSION}" ]; then echo "::error::Marketplace latest='${MKT_FINAL}' != '${RELEASE_VERSION}'" exit 91 diff --git a/CHANGELOG.md b/CHANGELOG.md index 79e15ae5..fb8cfd53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,11 +6,50 @@ This project follows Semantic Versioning. ## [Unreleased] +## [0.5.5] - 2026-11-17 + +Compatible audit and reliability patch. Public CLI/SDK exports and offline +analysis remain unchanged; the corrections below restore documented behavior. + +### Fixed + +- GitHub Action threshold failures survive a successful CLI process exit; + policy-suppressed findings do not fail the Action. CLI errors and bounded + process failures remain failures, and SARIF uses the canonical 2.1.0 writer. +- The Action builds its exact source checkout with pinned Node/pnpm setup and a + frozen install, then runs offline against the consumer. Clean-tag consumers + no longer depend on missing ignored CLI files. Setup needs registry access; + no generated `dist` is tracked (ADR-0034). +- SDK scans run the built-in rule catalog by default and append trusted extra + rules. VS Code now receives real findings, keeps packaged SDK identity/templates + available in its CommonJS bundle, and confines finding paths to the workspace. +- Action setup locates its own pinned manifest relative to the consumer workspace; + VS Code serializes overlapping refreshes per root and publishes completed snapshots. + Consumer diagnostics redact canonical path aliases on macOS as well. +- MCP tool reference matches all 16 live input schemas; scan `ci` controls the + severity exit hint. CLI `--root` now binds MCP startup ahead of environment/cwd + fallback without reopening per-tool root overrides. +- CI propagates extension lint/unit/Electron failures, verifies schema drift and + CLI smoke, derives version/VSIX names, and audits actual packaged content/CRC. + Extension tests assert real runtime data; VSIX excludes source maps and tools. +- Final Marketplace verification retries stale/unreadable visibility reads within + a fixed bound and still fails closed unless the exact release version is seen. +- Repaired README links, SDK example/signatures and portable path fixtures; + documented the separate historical task namespace and truthful Docs7 blockers. + +### Security + +- Updated compatible MCP SDK/Zod versions and affected runtime transitives; + production dependency audit reports zero known advisories. Existing development + tool advisories are separately triaged in TASK-0101, not hidden or suppressed. +- Marketplace-first manual gate, npm OIDC/provenance, exact-tag identity and + immutable artifact checks remain in force. No credential or permission change. + ### Added - Context7 library parsing configuration and optional Docs7 Free documentation - site manifest, with a guide for owner claiming, verification and automatic refresh; - no CLI/runtime, package version or existing hosting changes. + site manifest, with a guide for ownership, verification and automatic refresh; + documentation hosting/account verification remains separate from offline runtime. - Community integration docs for GitHub Spec Kit: new `docs/guides/spec-kit-bridge.md`, README ecosystem section and docs index link pointing at [`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge) @@ -612,4 +651,4 @@ PROJECT-CONTROL-0107 planning commit `c249a13` opens with the post-0158 state sy ### Fixed - Added NuGet package README metadata for local pack readiness. -- Refined self-scan stack accuracy so sample ASP.NET Core, Minimal API, TypeScript, and Tailwind CSS signals are not reported as the main repository stack. \ No newline at end of file +- Refined self-scan stack accuracy so sample ASP.NET Core, Minimal API, TypeScript, and Tailwind CSS signals are not reported as the main repository stack. diff --git a/README.md b/README.md index c26a42cd..4ad38746 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,7 @@ OpenCode, Copilot, Gemini, Cursor, Cline, any MCP-capable agent). ๐ŸฉบDiagnosticsackit diagnostics bundleackit.diagnostics.v1 + deterministic bundle-manifest.json (sha256 + redaction count), 5-secret [REDACTED] proof โšกBenchmarksbenchmarks/run.mjs7 deterministic fixtures, 8 metrics (coldScanMs/warmScanMs/incrementalMs/peakRssMb/filesPerSec/packMs/graphMs/cacheHitRatio), median-of-3 ๐Ÿ”ŒSDK v1import { scanRepository } from "@cynrath/agent-context-kit"sideEffects:false, type:module, exports {".","./mcp"}, AbortSignal <200ms, AckitError -๐ŸงฉVS Codeextensions/vscode0.5.4, Cynrath, lints Linters, onStartupFinished, readiness tree + Problems ACKITxxx + status-integrated Tasks view (canonical blockers/next actions, no mutation), <2MB VSIX โ€” Marketplace: Cynrath.ackit-vscode +๐ŸงฉVS Codeextensions/vscode0.5.5, Cynrath, lints Linters, onStartupFinished, readiness tree + Problems ACKITxxx + status-integrated Tasks view (canonical blockers/next actions, no mutation), <2MB VSIX โ€” Marketplace: Cynrath.ackit-vscode ๐Ÿค–MCPackit mcp serveOfficial SDK stdio, 16 read-only tools (incl. canonical ackit_status, workflow status, intent, checkpoint, verification bundle, drift, roles), 5 resources, 4 prompts, InMemoryTransport cancellation ๐Ÿ”Trust-Flow Demodocs/guides/demo-trust-flow.mdreproducible offline proof: missing proof blocks โ†’ bound independent verdict enables โ†’ mutation stales โ†’ fresh re-verification restores โ†’ handoff exports โ†’ second process resumes (tests/e2e/trust-flow-demo.test.ts) @@ -356,7 +356,7 @@ ackit diagnostics --json | jq .profile ackit diagnostics bundle --out ./ackit-diag.zip --redact-check ``` -Guides: [`docs/guides/watch-dashboard.md`](docs/guides/watch-dashboard.md) ยท Reference: [`docs/reference/diagnostics.md`](docs/reference/diagnostics.md) +Reference: [watch, dashboard and diagnostics commands](docs/reference/cli.md) --- @@ -386,13 +386,19 @@ ACKit is available on the VS Code Marketplace as From source: ```bash -pnpm --filter vscode build -vsce package # โ†’ ackit-vscode-0.5.4.vsix +pnpm install --frozen-lockfile +pnpm build +pnpm --filter ackit-vscode run build +node -e "require('node:fs').mkdirSync('artifacts', { recursive: true })" +cd extensions/vscode +npx --yes @vscode/vsce@4.1.1 package --no-dependencies --no-yarn --out ../../artifacts/ackit-vscode-0.5.5.vsix +cd ../.. +node scripts/check-vsix.mjs artifacts/ackit-vscode-0.5.5.vsix ``` Features: readiness tree, Problems `ACKITxxx`, graph โ€œinstructions for current fileโ€, tasks/policy/optimize, palette `Refresh/Show Graph/Optimize/Diagnostics`, file watcher debounced, no telemetry. -Guide: [`docs/guides/vscode.md`](docs/guides/vscode.md) +Guide: [`extensions/vscode/README.md`](extensions/vscode/README.md) --- @@ -402,10 +408,10 @@ Guide: [`docs/guides/vscode.md`](docs/guides/vscode.md) |---|---| | Architecture | [`docs/architecture/overview.md`](docs/architecture/overview.md) | | Concepts | `instruction-graph` ยท `context-budget` ยท `provider-profiles` ยท `readiness` ยท [`workflows`](docs/concepts/workflows.md) ยท [`intent`](docs/concepts/intent.md) ยท [`checkpoints`](docs/concepts/checkpoints.md) ยท [`evidence-verification`](docs/concepts/evidence-verification.md) | -| Guides | [`getting-started`](docs/guides/getting-started.md) ยท [`readiness`](docs/guides/readiness.md) ยท [`optimize`](docs/guides/optimize.md) ยท [`provider-profiles`](docs/guides/provider-profiles.md) ยท [`instruction-graph`](docs/guides/instruction-graph.md) ยท [`rule-packs`](docs/guides/rule-packs.md) ยท [`ci`](docs/guides/ci.md) ยท [`watch-dashboard`](docs/guides/watch-dashboard.md) ยท [`diagnostics`](docs/guides/diagnostics.md) ยท [`sdk`](docs/guides/sdk.md) ยท [`vscode`](docs/guides/vscode.md) ยท [`monorepo`](docs/guides/monorepo.md) ยท [`workflow-adoption`](docs/guides/workflow-adoption.md) ยท [`workflow-example`](docs/guides/workflow-example.md) ยท [`demo-trust-flow`](docs/guides/demo-trust-flow.md) ยท [`spec-kit-bridge`](docs/guides/spec-kit-bridge.md) | +| Guides | [`getting-started`](docs/guides/getting-started.md) ยท [`readiness`](docs/reference/cli.md) ยท [`optimize`](docs/reference/cli.md) ยท [`provider-profiles`](docs/reference/cli.md) ยท [`instruction-graph`](docs/concepts/instruction-graph.md) ยท [`rule-packs`](docs/reference/policy.md) ยท [`ci`](docs/guides/ci.md) ยท [`watch-dashboard`](docs/reference/cli.md) ยท [`diagnostics`](docs/reference/cli.md) ยท [`sdk`](docs/reference/sdk.md) ยท [`vscode`](extensions/vscode/README.md) ยท [`monorepo`](docs/guides/monorepo.md) ยท [`workflow-adoption`](docs/guides/workflow-adoption.md) ยท [`workflow-example`](docs/guides/workflow-example.md) ยท [`demo-trust-flow`](docs/guides/demo-trust-flow.md) ยท [`spec-kit-bridge`](docs/guides/spec-kit-bridge.md) | | Reference | `cli` ยท `config` ยท `rules` ยท `readiness` ยท `profile` ยท `rule-pack` ยท `instruction-graph` ยท `diagnostics` ยท `sdk` ยท `exit-codes` ยท `mcp` ยท `schemas` ยท [`drift`](docs/reference/drift.md) ยท [`policy`](docs/reference/policy.md) ยท [`status`](docs/reference/cli.md#cli-reference) ยท [`provider-surfaces`](docs/reference/provider-surfaces.md) | | Decisions | [`docs/decisions/`](docs/decisions/) ยท `v0.2.0`: [`docs/v0.2.0/`](docs/v0.2.0/) ยท `ADR-0025..0028`: workflow/evidence/checkpoint/policy-v2 | -| Tasks | [`docs/tasks/active`](docs/tasks/active) | +| Tasks | [`task records`](docs/tasks/README.md) | | Ecosystem | [Spec Kit bridge](docs/guides/spec-kit-bridge.md) โ€” community integration ([`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge)) connecting Spec Kit intent artifacts to ACKit tasks, evidence, verification gates, and handoffs | --- @@ -450,7 +456,7 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the docs-first workflow. ### ๐Ÿ”– Versioning -Development: **`0.5.4`** on `master` ยท Latest stable: **`0.5.4`** ยท [Changelog](CHANGELOG.md) ยท [Releases](https://github.com/Cynrath/agent-context-kit/releases/latest) ยท `latest โ†’ 0.5.4` via OIDC Trusted Publishing with provenance. Stable pointer: [`release-state.json`](release-state.json). Legacy `.NET/NuGet 1.0.0-rc.1` at `258918b` is frozen. +Development: **`0.5.5`** on `master` ยท Latest stable: **`0.5.4`** ยท [Changelog](CHANGELOG.md) ยท [Releases](https://github.com/Cynrath/agent-context-kit/releases/latest) ยท `latest โ†’ 0.5.4` via OIDC Trusted Publishing with provenance. Stable pointer: [`release-state.json`](release-state.json). Legacy `.NET/NuGet 1.0.0-rc.1` at `258918b` is frozen. --- diff --git a/action.yml b/action.yml index 7f051dce..f08e8cd7 100644 --- a/action.yml +++ b/action.yml @@ -24,8 +24,40 @@ inputs: outputs: findings-json: description: "path to findings JSON" + value: ${{ steps.ackit.outputs.findings-json }} sarif-path: description: "SARIF file path when upload-sarif=true" + value: ${{ steps.ackit.outputs.sarif-path }} runs: - using: "node24" - main: "dist/action/index.js" + using: "composite" + steps: + # actions/setup-node@v4 + - uses: actions/setup-node@ae0d4ed08881f17d1511386f5be3e62356acd4a6 + with: + node-version: "24" + - name: Locate the Action manifest + id: action-package + shell: bash + env: + ACKIT_ACTION_PATH: ${{ github.action_path }} + run: node "${ACKIT_ACTION_PATH}/scripts/action-package-path.mjs" >> "${GITHUB_OUTPUT}" + # pnpm/action-setup@v4 + - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 + with: + package_json_file: ${{ steps.action-package.outputs.path }} + - name: Build the exact Action source + shell: bash + working-directory: ${{ github.action_path }} + run: | + pnpm install --frozen-lockfile --ignore-scripts --filter @cynrath/agent-context-kit + pnpm build + - name: Run ACKit against the consumer + id: ackit + shell: bash + env: + ACKIT_ACTION_PATH: ${{ github.action_path }} + INPUT_COMMAND: ${{ inputs.command }} + INPUT_ARGS: ${{ inputs.args }} + INPUT_FAIL_THRESHOLD: ${{ inputs.fail-threshold }} + INPUT_UPLOAD_SARIF: ${{ inputs.upload-sarif }} + run: node "${ACKIT_ACTION_PATH}/dist/action/index.js" diff --git a/dist/action/index.js b/dist/action/index.js deleted file mode 100644 index 1908c51c..00000000 --- a/dist/action/index.js +++ /dev/null @@ -1,150 +0,0 @@ -#!/usr/bin/env node -// Minimal GitHub Action runtime for ACKit (TASK-0014) -// Uses @actions/core if available, else fallback to console. No shell interpolation, uses execFile. -import { spawnSync } from "node:child_process"; -import { writeFileSync, existsSync } from "node:fs"; -import path from "node:path"; -import process from "node:process"; - -function getInput(name) { - const envName = `INPUT_${name.replace(/ /g, "_").toUpperCase().replace(/-/g, "_")}`; - return process.env[envName] ?? ""; -} - -function safeSplitArgs(input) { - if (!input || input.trim() === "") return []; - // Simple shell-like split respecting double quotes, no evaluation - const args = []; - let cur = ""; - let inQuote = false; - for (let i = 0; i < input.length; i++) { - const c = input[i]; - if (c === '"' && (i === 0 || input[i - 1] !== "\\")) { - inQuote = !inQuote; - continue; - } - if (c === " " && !inQuote) { - if (cur.length > 0) { - args.push(cur); - cur = ""; - } - continue; - } - cur += c; - } - if (cur.length > 0) args.push(cur); - return args; -} - -function severityRank(s) { - const map = { low: 1, medium: 2, high: 3, critical: 4 }; - return map[s?.toLowerCase()] ?? 0; -} - -async function run() { - const command = getInput("command") || "scan"; - const argsRaw = getInput("args") || ""; - const failThreshold = getInput("fail-threshold") || "high"; - const uploadSarif = getInput("upload-sarif") === "true"; - const extraArgs = safeSplitArgs(argsRaw); - - const runnerTemp = process.env["RUNNER_TEMP"] || process.env["TMPDIR"] || "/tmp"; - const findingsJsonPath = path.join(runnerTemp, "ackit-findings.json"); - const sarifPath = path.join(runnerTemp, "ackit.sarif"); - - // Resolve CLI entry (dist/cli/index.js) - const cliPath = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")), "..", "cli", "index.js"); - - // For scan, we invoke ackit scan --json and capture findings - let findings = []; - let exitCode = 0; - try { - const cliArgs = [cliPath, command, ...extraArgs, "--json"]; - // Use node to run CLI - const result = spawnSync(process.execPath, cliArgs, { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 }); - if (result.stdout) { - try { - const parsed = JSON.parse(result.stdout); - findings = parsed.findings ?? parsed.suggestions ?? []; - // Write findings JSON to temp - writeFileSync(findingsJsonPath, JSON.stringify(parsed, null, 2), "utf8"); - // Emit outputs via GITHUB_OUTPUT if available - const outPath = process.env["GITHUB_OUTPUT"]; - if (outPath) { - try { - const fs = await import("node:fs/promises"); - await fs.appendFile(outPath, `findings-json=${findingsJsonPath}\n`); - if (uploadSarif) await fs.appendFile(outPath, `sarif-path=${sarifPath}\n`); - } catch {} - } - // Annotations: map severity to ::error/::warning - for (const f of findings.slice(0, 10)) { - const lvl = (f.severity ?? "low").toLowerCase(); - const msg = `${f.ruleId ?? f.id ?? "ACKIT"}: ${f.message ?? ""}`.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A"); - const file = (f.relativePath ?? f.evidence?.[0]?.relativePath ?? "unknown").replace(/%/g, "%25"); - const line = f.line ?? f.evidence?.[0]?.line ?? 1; - const annotation = lvl === "critical" || lvl === "high" ? "error" : lvl === "medium" ? "warning" : "notice"; - console.log(`::${annotation} file=${file},line=${line}::${msg}`); - } - // SARIF if requested - if (uploadSarif) { - const sarif = { - $schema: "https://json.schemastore.org/sarif-2.1.0.json", - version: "2.1.0", - runs: [ - { - tool: { driver: { name: "ackit", version: "0.2.0" } }, - results: findings.map((f) => ({ - ruleId: f.ruleId ?? f.id ?? "ACKIT", - level: f.severity === "high" || f.severity === "critical" ? "error" : f.severity === "medium" ? "warning" : "note", - message: { text: f.message ?? "" }, - locations: [ - { - physicalLocation: { - artifactLocation: { uri: f.relativePath ?? f.evidence?.[0]?.relativePath ?? "unknown" }, - }, - }, - ], - })), - }, - ], - }; - writeFileSync(sarifPath, JSON.stringify(sarif, null, 2), "utf8"); - } - // Job summary - const summaryPath = process.env["GITHUB_STEP_SUMMARY"]; - if (summaryPath) { - try { - const fs = await import("node:fs/promises"); - const counts = {}; - for (const f of findings) counts[f.severity ?? "low"] = (counts[f.severity ?? "low"] ?? 0) + 1; - let md = `## ACKit ${command} โ€” ${findings.length} finding(s)\n\n| Severity | Count |\n|---|---|\n`; - for (const sev of ["critical", "high", "medium", "low"]) if (counts[sev]) md += `| ${sev} | ${counts[sev]} |\n`; - if (findings.length > 0) md += `\nTop: ${findings[0]?.ruleId ?? findings[0]?.id} โ€” ${findings[0]?.message ?? ""}\n`; - await fs.appendFile(summaryPath, md, "utf8"); - } catch {} - } - // Fail threshold gating - const maxRank = findings.reduce((m, f) => Math.max(m, severityRank(f.severity)), 0); - const thrRank = severityRank(failThreshold); - if (maxRank >= thrRank && findings.length > 0) { - console.error(`::error::fail-threshold ${failThreshold} exceeded`); - exitCode = 1; - } - exitCode = result.status ?? exitCode; - } catch (e) { - console.error(`::error::failed to parse CLI JSON: ${e}`); - exitCode = 1; - } - } else { - if (result.stderr) console.error(result.stderr); - exitCode = result.status ?? 1; - } - } catch (e) { - console.error(`::error::action failed: ${e}`); - exitCode = 1; - } - process.exit(exitCode); -} - -run(); diff --git a/docs/decisions/ADR-0034-source-built-action-distribution.md b/docs/decisions/ADR-0034-source-built-action-distribution.md new file mode 100644 index 00000000..dac2853f --- /dev/null +++ b/docs/decisions/ADR-0034-source-built-action-distribution.md @@ -0,0 +1,44 @@ +# ADR-0034: Source-built GitHub Action distribution + +Status: Accepted ยท Date: 2026-11-17 ยท Task: TASK-0098 + +## Context + +ADR-0020 specified a self-contained Node action but its implementation tracks a +handwritten `dist/action/index.js` with no owning source. Tags omit the referenced +CLI and dependencies; the dogfood build hides the missing runtime. Current +repository governance prohibits tracking generated `dist`. Committing an entire +CLI/dependency bundle would contradict that rule and duplicate the npm runtime. + +## Decision + +Supersede only ADR-0020's distribution/entrypoint choice with a composite Action +that builds the exact tagged source in its own checkout. Preserve inputs, +outputs, least privilege, injection-safe argv, optional SARIF and offline product +execution. The original ADR is retained verbatim as historical context. + +1. Pin setup-node and pnpm/action-setup to reviewed full SHAs. Select Node 24 and + the action checkout's exact `packageManager` version. +2. Frozen-install the action workspace and build its canonical CLI/Action source. + Setup may download locked dependencies; no consumer package script is run. +3. Run the built TypeScript Action entry with input values passed through + environment variables. Resolve CLI files relative to the Action installation; + the working directory remains the consumer repository. +4. No network is used by the CLI/SDK/MCP/Action execution code. No `dist`, bundled + dependencies, package archives or generated runtime is committed. +5. A clean exported checkout consumed from an unrelated fixture, plus hosted + dogfood without a preparatory install/build, validates the whole bootstrap. + +## Consequences and alternatives + +Consumers require registry access during setup and incur an install/build cost. +Runtime remains the same canonical source/version, without an npm publication +race at tag creation. A generated committed bundle and runtime `npx latest` were +rejected for governance and reproducibility reasons respectively. Revisit only +through a separate task if measured setup cost warrants a distribution change. + +## Security and rollback + +Trusted Action source, frozen lockfile, pinned setup actions and environment/argv +boundaries apply. No permission expansion or automatic upload. A forward PR can +correct the bootstrap; never move existing tags or change published artifacts. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 56195a66..a81ec7df 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -45,3 +45,9 @@ v0.5 line additions (Accepted 2026-09-05, governing TASK-0078 โ€ฆ TASK-0086): - ADR-0030 deterministic verification state binding (verdict โ†” bundle/state digests, staleness + replay at the binding layer) - ADR-0031 structural verifier independence + replay hardening (reviewed-bundle proof, independence gate, review-artifact lifecycle) - ADR-0032 canonical read-only status projection (composed task/stage/blockers/staleness/next-actions, no second engine) + +Distribution correction (Accepted 2026-11-17): + +- [ADR-0034 source-built Action distribution](ADR-0034-source-built-action-distribution.md) + amends ADR-0020's entrypoint/bootstrap while preserving offline runtime and + avoiding committed generated output. diff --git a/docs/guides/ci.md b/docs/guides/ci.md index 7ddc30b1..94dcebfa 100644 --- a/docs/guides/ci.md +++ b/docs/guides/ci.md @@ -16,6 +16,32 @@ Matrix: **ubuntu + windows + macos ร— Node 22 + 24**. TASK-0286 hardens this further (SHA-pinned actions, package smoke, self-scan, MCP smoke). +## GitHub Action distribution + +The Action keeps `command`, `args`, `fail-threshold`, `upload-sarif` and the +`findings-json` / `sarif-path` outputs. Pin a published tag or full commit SHA. +It sets up Node 24 and the exact pnpm version from its own `package.json`, then +installs the frozen lockfile and builds in the Action checkout. Setup requires +registry access; the resulting CLI execution is offline and scans the consumer's +working directory. Consumer dependencies and scripts are never installed or run. + +`fail-threshold` is inclusive (`low|medium|high|critical`) for scan findings and +optimize suggestions, ignores explicitly policy-suppressed findings, and cannot +clear a nonzero CLI exit code. The original command JSON stays intact. SARIF is +generated only when requested and is not uploaded automatically. Consumers need +`contents: read`; SARIF upload is a separate opt-in step with its own permissions. +Use the Action outputs to locate generated files rather than guessing paths. + +For `drift check`, blocking maps to high and warning maps to medium for the +Action threshold; CLI `--ci` errors are still preserved independently. Its +task-level SARIF results have no fabricated file location. SARIF file paths are +URI-encoded, including spaces, reserved characters and Unicode. + +`pnpm run smoke:action` exports clean source into a separate Action checkout, +installs/builds it and scans an unrelated Git fixture without consumer runtime +files. `pnpm run smoke:action --ref vX.Y.Z` repeats the check from a release tag. +ADR-0034 records the source distribution decision; generated `dist` is untracked. + ## Using ACKit as a gate in your repo ```bash diff --git a/docs/guides/context7-docs7.md b/docs/guides/context7-docs7.md index 333bca44..051e9128 100644 --- a/docs/guides/context7-docs7.md +++ b/docs/guides/context7-docs7.md @@ -28,12 +28,14 @@ Open the already-owned library's **Admin** page and select the orange **Apply fo ## 4. Connect Docs7 Free (optional; existing GitHub Pages stays active) 1. Open [Docs7](https://context7.com/docs7) while signed into Context7. -2. Add a new site from GitHub; select `Cynrath/agent-context-kit`. +2. In the teamspace's Docs7 tab, choose **Add new repository**, then **Form**; + select `Cynrath/agent-context-kit`. 3. Set production branch to `master`, and **Docs path** to `docs`. The `docs/docs.json` file defines the navigation and `docs/index.mdx` is the entry page. 4. Publish the site. Keep the assigned `*.docs7.io` address separate from existing GitHub Pages until you intentionally decide otherwise. 5. Enable **Add to Context7** when connecting the repository (or use the site's **Context7** tab) so successful production builds refresh the library automatically. Do not create a duplicate library if the original GitHub library is already registered. -Docs7 Free currently allows up to three sites. The hosted documentation site and agent-readable endpoints are available on Free; autonomous Docs7 documentation editing agents and PR previews require Pro. +See [Docs7 plans](https://context7.com/docs/docs7/plans) for current site limits, +preview access and documentation-editing agent availability. ## 5. Verify deployment and indexing diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md index 98cc0081..f7ece6fc 100644 --- a/docs/reference/mcp.md +++ b/docs/reference/mcp.md @@ -11,15 +11,15 @@ truth). | Tool | Arguments | Returns | |---|---|---| -| ackit_scan | changed?, ci?, root? | canonical scan report JSON + exit_code_hint | -| ackit_doctor | root? | config ok/errors + task-doctor integrity | -| ackit_pack | maxTokens?, format?, includeGlobs?, root? | pack markdown or JSON | -| ackit_instruction_graph | root? | instruction graph nodes | -| ackit_list_skills | root? | skill records | -| ackit_validate_skills | root? | tiered issues | -| ackit_list_tasks | all?, root? | task rows (id/status/title) | -| ackit_get_task | id, root? | full task doc or unknown-task error | -| ackit_policy_check | root? | policy chain + digest + diagnostics | +| ackit_scan | changed?, ci? | canonical scan report JSON + exit_code_hint | +| ackit_doctor | โ€” | config ok/errors + task-doctor integrity | +| ackit_pack | maxTokens?, format? | pack markdown or JSON | +| ackit_instruction_graph | โ€” | instruction graph nodes | +| ackit_list_skills | โ€” | skill records | +| ackit_validate_skills | โ€” | tiered issues | +| ackit_list_tasks | all? | task rows (id/status/title) | +| ackit_get_task | id | full task doc or unknown-task error | +| ackit_policy_check | โ€” | policy chain + digest + diagnostics | | ackit_workflow_status | taskId | workflow profile/stage/required artifacts + effective evidence/verdict requirements (null for legacy tasks) | | ackit_get_intent | id | intent document + fingerprint | | ackit_get_checkpoint | taskId | latest checkpoint + resume context | @@ -28,6 +28,19 @@ truth). | ackit_status | taskId? | canonical read-only task status snapshot (same `ackit.status.v1` contract as CLI `status`) | | ackit_list_roles | โ€” | portable role contracts | +The repository root is resolved once at server construction (`--root` for the +CLI, `ACKIT_ROOT`, or `createAckitMcpServer(repositoryRoot)` for the SDK). Tools +cannot override that boundary. Per-call `root` and pack `includeGlobs` are not +supported inputs; repository configuration and the canonical pack safety gates +control discovery. + +`ackit_scan.changed` defaults to `false`; `true` restricts the scan to Git changes. +`ci` defaults to `false`: report-only scans append `exit_code_hint=0` even when +findings exist. With `ci: true`, the hint is `1` only when an unsuppressed finding +meets the configured policy severity threshold; otherwise it is `0`. This hint +does not terminate the MCP server or turn findings into a protocol error. CLI +readiness gates are separate from this severity hint. + Write tools are intentionally absent (state mutation stays CLI-only by explicit decision). Any future write tool requires a new ADR with an explicit capability/permission gate design before registration. diff --git a/docs/reference/sdk.md b/docs/reference/sdk.md index 6b802fd5..fb227a3c 100644 --- a/docs/reference/sdk.md +++ b/docs/reference/sdk.md @@ -9,16 +9,16 @@ The programmatic SDK is the single supported import for embedding ACKit in Node. | Symbol | Kind | Description | |---|---|---| -| `scanRepository(root, opts?)` | function | Scans a repository, returns `ScanResult` (deterministic findings, diagnostics, filesScanned). `opts.signal?: AbortSignal` cancels within 200ms. | -| `loadAckitConfig(root, opts?)` | function | Loads `ackit.yml` + policy chain, returns `{ok, config}` or `{ok:false, errors}` with `AckitError`-compatible codes. | +| `scanRepository(root, opts?)` | function | Scans a repository, returns `ScanResult` (deterministic findings, diagnostics, filesScanned). Accepts `opts.signal?: AbortSignal`. | +| `loadAckitConfig(rootPath, opts?)` | function | Loads and validates `ackit.yml`, merges configuration defaults and returns `{ok, config}` or `{ok:false, errors}`. `rootPath` is a directory string. | | `buildContextPack(root, opts?)` | function | Builds a budgeted deterministic context pack (`PackResult`). `opts.signal` supported. | | `buildInstructionGraph(root, opts?)` | function | Builds the instruction graph (`InstructionGraph`). `opts.signal` supported. | | `resolveEffectiveStack(graph, provider, forPath?)` | function | Pure function resolving the effective instruction stack for a provider/path. | | `analyzeOptimize(root, opts?)` | function | Optimization findings + suggestions (pack/context waste analysis). | | `validateSkills(root)` | function | Validates `.agents/skills/*/SKILL.md` set, returns `{skills, issues}`. | -| `evaluateRulePacks(root, opts?)` | function | Evaluates declarative rule packs (exported since v0.2.0). | -| `loadRulePacks(root)` | function | Loads rule pack documents. | -| `scoreRepository(root, opts?)` | function | Readiness scoring engine (exported since v0.2.0). | +| `evaluateRulePacks(effectivePacks, context)` | function | Evaluates loaded declarative rules against repository files/configuration (exported since v0.2.0). | +| `loadRulePacks(root, rulePackPaths)` | function | Loads the explicit repository-relative rule-pack paths. | +| `scoreRepository(inputs, opts?)` | function | Scores collected graph/pack/scan/skills/policy/task inputs (exported since v0.2.0). | | `detectProfiles`, `loadBuiltInProfiles`, `resolveProfile` | functions | Stack/profile detection and resolution. | | `ProfileSchema` | constant | Stack-profile zod schema. | | `READINESS_ENGINE_VERSION` | constant | Readiness engine version marker. | @@ -65,13 +65,29 @@ Additions require ADR + contract test update; the allowlist test fails on accide ## Error model +For scanning, packs, graphs, skills and rule-pack loading, `root` is a descriptor +`{ canonicalPath: string }`, not a path string. Resolve it with Node's `realpath`: + +```js +import { realpath } from "node:fs/promises"; +const root = { canonicalPath: await realpath(process.cwd()) }; +``` + +`scanRepository` runs built-in rules plus `opts.extraRules` through the shared +pipeline. It does not load `ackit.yml` or apply its external policy chain; +configured CLI/MCP scans add that orchestration. Supply explicit limits and +exclusions when embedding the lower-level SDK scanner. + ```ts import { AckitError, scanRepository } from "@cynrath/agent-context-kit"; +import { realpath } from "node:fs/promises"; +const root = { canonicalPath: await realpath(process.cwd()) }; +const signal = new AbortController().signal; try { const result = await scanRepository(root, { signal }); } catch (e) { if (e instanceof DOMException && e.name === "AbortError") { - console.log("aborted within 200ms"); + console.log("aborted"); } else if (e instanceof AckitError) { console.error(e.code, e.message, e.remediation); } else if (e instanceof Error) { @@ -84,14 +100,20 @@ Stable codes: `CONFIG-UNKNOWN-KEY` (did-you-mean hint in `remediation`), `CONFIG ## Cancellation (AbortSignal) -All async SDK entries accept `{ signal?: AbortSignal }` and reject with `DOMException { name:"AbortError" }` within 200ms when `signal.aborted` is true before the call, and cooperatively abort mid-flight where checkpoints exist (scan batches, pack checkpoints, graph per-file). +The scanning, context-pack and instruction-graph entries accept +`{ signal?: AbortSignal }` and reject with `DOMException { name:"AbortError" }` +within 200ms when `signal.aborted` is true before the call. Mid-flight cancellation +is cooperative at scan batches, pack checkpoints and graph file boundaries; +it is not a fixed wall-clock guarantee for arbitrary caller-supplied rules. ```ts import { scanRepository } from "@cynrath/agent-context-kit"; +import { realpath } from "node:fs/promises"; +const root = { canonicalPath: await realpath(process.cwd()) }; const ac = new AbortController(); setTimeout(() => ac.abort(), 10); try { - const result = await scanRepository(process.cwd(), { signal: ac.signal }); + const result = await scanRepository(root, { signal: ac.signal }); console.log(result.findings.length); } catch (e) { if (e instanceof DOMException && e.name === "AbortError") console.log("aborted"); diff --git a/docs/tasks/README.md b/docs/tasks/README.md new file mode 100644 index 00000000..850507a1 --- /dev/null +++ b/docs/tasks/README.md @@ -0,0 +1,17 @@ +# Task record namespaces + +The current TypeScript task store reads `docs/tasks/active/` and, with `--all`, +`docs/tasks/archive/`. Those two directories share one live ID namespace. Create +new records with the repository-built CLI; `task doctor` validates their IDs, +dependencies and single-active state. + +Root-level `TASK-*.md` and `PROJECT-CONTROL-*.md` files preserve the earlier +implementation and migration history. They use a separate namespace: a matching +numeric ID in that history and in the current store is not a duplicate live +task. The historical files are intentionally not loaded or renumbered by the +current task store. Keep their contents and paths as evidence. + +Completed current tasks are archived only after their literal acceptance +criteria and completion evidence pass. Historical blocked records retain the +unperformed/superseded acceptance items they describe; a later successful release +does not retroactively complete them. diff --git a/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md b/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md index 52573e32..025d5e6a 100644 --- a/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md +++ b/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md @@ -1,7 +1,7 @@ --- id: "TASK-0097" title: "Context7 ownership-ready configuration and Docs7 documentation distribution" -status: active +status: blocked schemaVersion: 2 dependencies: [] createdAt: "2026-10-15" @@ -71,3 +71,31 @@ Revert the documentation/configuration PR; keep historical tags/releases untouch ## Completion notes PENDING. The GitHub connector provides file edits but no checkout/execution; source checkout failed DNS resolution to github.com (`Could not resolve host: github.com`) and pnpm is unavailable in the container, so the repository-built CLI could not allocate a task ID. `TASK-0097` uses the next unused ID after checked `TASK-0096` as a documented manual fallback. No local validation, Docs7 deploy, claim or badge may be asserted. + +### Audit checkpoint 2026-11-17 + +The source checkout and pinned pnpm are now executable. The guide already says +the maintainer's teamspace owns the library, but this record has no successful +Docs7 production build, endpoint or exact-head CI evidence. Literal acceptance +therefore remains open; do not complete/archive it. TASK-0101 will reconcile the +local checks and external evidence. TASK-0098 is the next dependency-ready audit +task; historical blocked TASK-0087/0092/0093 remain untouched. + +### Local evidence reconciliation 2026-11-17 (TASK-0101) + +- The current official Context7 schema was fetched over HTTPS (200) and + `context7.json` validated with AJV plus standard formats: true, no errors. +- All 32 `docs/docs.json` navigation routes resolve to actual `.md`/`.mdx` files. + The required name/colors/navigation and filterSidebar fields match the current + official Docs7 quickstart/configuration docs. The guide now links current plan + details instead of making the obsolete claim that previews require Pro. +- Formal compilation of the downloaded upstream Docs7 schema is inconclusive: + AJV's Unicode regex mode rejects its unrelated PostHog API-key pattern + `^phc\_` (`Invalid escape` at + `anyOf.0.properties.integrations.properties.posthog.properties.apiKey.pattern`). + The repository configuration contains no PostHog integration. No schema gate + was disabled or provider schema rewritten to hide this external incompatibility. +- **Not run:** Docs7 production build, live site/agent endpoints, account/admin + ownership or badge verification. No deployment/account action is authorized + by the corrective patch tasks. The task stays blocked, not completed/archived; + this external documentation work is not a patch-publication prerequisite. diff --git a/docs/tasks/active/TASK-0103-authorized-patch-publication-and-public-surface-.md b/docs/tasks/active/TASK-0103-authorized-patch-publication-and-public-surface-.md new file mode 100644 index 00000000..bb5ed7f4 --- /dev/null +++ b/docs/tasks/active/TASK-0103-authorized-patch-publication-and-public-surface-.md @@ -0,0 +1,142 @@ +--- +id: "TASK-0103" +title: "Authorized patch publication and public-surface verification" +status: pending +schemaVersion: 2 +dependencies: + - "TASK-0102" + - "TASK-0105" +createdAt: "2026-11-17" +completedAt: null +--- + + +## Purpose + +Publish and independently verify the compatible patch through the repository's +PR and Marketplace-first, npm-second controlled-release process. + +## Explicit user authorization (2026-11-17) + +The goal objective authorizes scoped file changes/tests/docs/Git operations; +feature-branch commits and ordinary pushes; PR creation and merge to master; +creation/push of a NEW next-patch tag (planned v0.5.5); VS Code Marketplace +publication; tag-triggered npm OIDC Trusted Publishing; and GitHub Release +creation with audited VSIX assets. This is authorization for these exact actions +in this task, not permission for direct master push or credential disclosure. +Force push/reset/rebase/history rewrite/tag movement/deletion, workflow dispatch +or rerun, deployments, secret/permission changes and legacy .NET releases remain +prohibited. No release artifact may be overwritten. + +## Scope + +- Push the fully committed branch, create a reviewable PR and wait for successful + exact-head CI (all Node 22/24 ร— OS jobs, extension/Electron, consumer smokes). +- Merge through the existing PR procedure; verify final master SHA and checks. +- Build/audit the exact release VSIX; publish outside workflow with already + authorized maintainer authentication if available, otherwise provide the exact + audited artifact/command and request the missing user authentication step. +- Verify Marketplace target BEFORE pushing the new tag. Let the tag-triggered + release workflow perform npm OIDC publication and GitHub Release. +- Verify registry/latest/fresh npx + SDK + MCP, clean external Action consumer + from the new tag, Marketplace/VSIX/Release identity and checksums. +- Only after live success, update stable pointer/current install pins through a + follow-up PR with exact-head CI; record final master/task evidence truthfully. + +## Out of scope + +- Direct master push, workflow dispatch/rerun, deployment or site publication; + credential creation/storage; tag or immutable version replacement; changes to + unrelated repositories; closing old blocked tasks without literal evidence. + +## Affected files + +- Active/archive task evidence, `release-state.json`, current stable install + references after live success, PR/release notes via UTF-8 body files; ignored + VSIX/tarball/checksum outputs only. + +## Dependencies + +TASK-0102 and all prior tasks. Missing Marketplace authentication is a real +external blocker; do independent authorized work first, never partial-publish npm. + +## Required tests + +- Exact-head PR CI, post-merge CI, target absence, rebuilt VSIX preflight, + Marketplace live reads, tag-trigger release run, npm latest/shasum/consumer + smokes, SDK/MCP entrypoints, tag Action consumer, Release asset checksum, + stable-pointer parity, final ACKit/Git cleanliness. + +## Acceptance criteria + +- [ ] PR merged only after all exact-head CI checks pass; master SHA verified. +- [ ] Marketplace target visible before new immutable tag triggers npm publication. +- [ ] npm latest, fresh CLI/SDK/MCP and new-tag external Action consumer pass. +- [ ] GitHub Release tag/VSIX identity and downloaded asset checksum pass. +- [ ] Stable-pointer bookkeeping merged with CI; final master clean/aligned; + task evidence and open blockers match the actual public state. + +## Test steps + +1. Recheck remote HEAD, PR checks, target/tag absence and release prerequisites. +2. Publish audited Marketplace VSIX using available authorized authentication; + never print credentials. Stop the dependent tag/npm sequence if unavailable. +3. Push new annotated tag only after Marketplace read-back succeeds; monitor + the automatic release run and repair only via authorized forward changes. +4. Independently read all published channels, install in a fresh isolated + consumer, compare checksums and merge truthful stable bookkeeping. + +## Security considerations + +Marketplace-first, npm OIDC/provenance, exact-tag/version checks, no overwrite, +no credential logging and least privilege remain mandatory. No production data +or schema migration. No new credential or secret/permission mutation. + +## Risks + +- Marketplace authentication may require the user. Replicas may be stale; use + bounded repeated read-only observations. If release fails, preserve tag and + published artifacts, record the exact stage and do not rerun prohibited work. + +## Rollback plan + +Before publication, forward corrective PR. After publication, only a NEW patch +can correct artifacts; never overwrite/repoint/delete the released version. + +## Completion notes + +Plan allocated by repository CLI on 2026-11-17. No publication or tag action yet. + +### Publication preflight 2026-11-17 + +- TASK-0098/0099/0100/0101/0104/0102 are verified and archived. Runtime correction + commit `a0e077c`; release preparation `eae5351`; current source/extension 0.5.5. + Full local suite: 772 PASS / 3 existing Windows privilege skips; extension + 8 unit + 6 Electron PASS; explicit CLI/package/Action consumers, schemas, + SARIF validation, offline, production audit and ACKit gates PASS. +- Local audited VSIX: 414975 bytes, SHA-256 + `8fa4cfc2f804f1440fcf1c5abe215570b7ee5c4c1762654a53676696c8d9fd9f`; + tarball: 497350 bytes, SHA-256 + `699437eff29c9dbd74ccd7104e2116ea1a384229cfb1b4e65cc49c88fa6b6a7f`. +- Existing stored Cynrath publisher was found and `vsce@4.1.1 verify-pat Cynrath` + exited 0 (publish-right verification). No secret value was printed or written + to repository/log files. No new credential or permission was created. +- Remote master is `64a9c9d56ea36eb475de29d050596b506264a07e`; strict rules require + all 12 established CI contexts. No release-owned open PR exists yet. The + branch will be pushed only after this status/evidence commit and clean-tree + verification. Publishing still waits for exact-head PR and master checks. +- npm latest/Marketplace are 0.5.4; npm 0.5.5 and remote tag are absent at the + preparation read. Stable pointer remains 0.5.4. Recheck immediately before + publishing; no immutable version or existing tag will be changed. + +### Hosted CI checkpoint โ€” publication held + +PR #43 exists at head `5daa10f9c572462cd89265b73f0affc5d9bb8578`. Linux and +Windows verification passed, but Action setup, extension lifecycle and macOS +diagnostic redaction failed. Required checks correctly block merge. TASK-0105 +owns the observed corrections and actual new-head CI proof; this task resumes +afterward. No master merge, Marketplace publication, tag, npm publication or +GitHub Release has been performed. Docs7 Preview separately reported success; +it is not evidence of the production/account acceptance in TASK-0097. + +Dependencies: TASK-0102 diff --git a/docs/tasks/active/TASK-0105-hosted-ci-action-setup-path-and-extension-refres.md b/docs/tasks/active/TASK-0105-hosted-ci-action-setup-path-and-extension-refres.md new file mode 100644 index 00000000..93ab5061 --- /dev/null +++ b/docs/tasks/active/TASK-0105-hosted-ci-action-setup-path-and-extension-refres.md @@ -0,0 +1,128 @@ +--- +id: "TASK-0105" +title: "Hosted CI Action setup path and extension refresh race correction" +status: active +schemaVersion: 2 +dependencies: + - "TASK-0102" +createdAt: "2026-11-17" +completedAt: null +--- + + +## Purpose + +Correct the actual PR #43 hosted failures before authorized publication. User +authorized scoped fixes, tests, commits, ordinary branch pushes and PR work on +2026-11-17. No old workflow run may be dispatched or rerun. + +## Scope + +- Action dogfood job 134079004647 failed before build: pinned pnpm/action-setup + joins GITHUB_WORKSPACE with package_json_file, so the composite's absolute + Action manifest path resolves incorrectly. Derive a workspace-relative path + to the Action's own pinned packageManager without copying a release number or + reading the consumer's packageManager. Test different checkout/consumer paths. +- Extension job 134079005179 failed the real lifecycle finding assertion. + Concurrent watcher/manual refreshes share one abort controller and mutate/re- + publish the old snapshot even on cancellation. Serialize refreshes per root, + publish fresh completed snapshots atomically, and abort safely on disposal. + Preserve the real lifecycle assertion and add overlapping-request coverage. +- macOS jobs 134079005992/134079006277 failed the diagnostic redaction assertion: + actual cwd is /private/var while the supplied temporary path is /var. Redact + both declared and canonical aliases, longest first. Keep exact error/stdout/ + redaction assertions and test an actual link alias where portable. +- Preserve exact-head CI requirements and all gates; push successor commits to + trigger normal PR CI. Rebuild/re-audit changed artifacts before publication. + +## Out of scope + +- New public SDK/CLI features, dependency upgrades, relaxed tests/timeouts, + workflow dispatch/rerun, permission/secret changes, publication or tag actions. + +## Affected files + +- `action.yml`, a narrow Action manifest-path helper, Action distribution and + independent-consumer tests; workspace refresh service and real Electron tests; + consumer-command diagnostic helper/tests; affected task/CI guide notes. + +## Dependencies + +TASK-0102 (and its full audit chain). TASK-0103 waits on this correction. + +## Required tests + +- Action path/consumer/diagnostic contracts, root lint/format/typecheck/build/full + suite, extension strict lint/typechecks/unit/Electron, real exported consumer, + offline/ACKit gates and new-head required PR CI including macOS. + +## Acceptance criteria + +- [x] Pinned pnpm setup reads the Action manifest correctly for local and + external consumer layouts; no preparatory dogfood build or mutable version pin. +- [x] Every explicit overlapping refresh awaits a completed current scan; + lifecycle/diagnostics assertions pass with disposal/cancellation respected. +- [x] Canonical temporary path aliases are fully redacted on macOS and other + hosts without weakening the exact stdout/status/path assertions. +- [~] Local focused/full/host checks and all required exact-head hosted checks + pass; failures and corrective evidence are recorded truthfully. + +## Test steps + +1. Preserve the failed job logs and inspect the pinned setup implementation. +2. Add overlapping-refresh and path-layout/alias regressions before the fixes; + record reproduced failures where the local platform permits. +3. Apply minimal owner-side changes; run local focused/full/extension/consumer + checks and normal successor commits/pushes to PR #43. +4. Wait for actual new-head CI proof; no reruns, skipped tests or gate bypass. + +## Security considerations + +Action path comes only from trusted Action metadata and the workspace context, +not consumer-controlled tool input. No untrusted consumer script is installed. +Maintain root-bound file access, offline execution, credential redaction and +strict types. No data migration, production mutation or permission change. + +## Risks + +- Queueing changes refresh timing; preserve completed-snapshot semantics without + performance claims and test actual overlapping commands in the host. +- Path aliases differ by OS; local link fixtures supplement, but never replace, + required real macOS CI evidence. + +## Rollback plan + +Forward corrective commit/PR only; no history rewrite or immutable artifact change. + +## Completion notes + +Planned from actual hosted failures on PR head +`5daa10f9c572462cd89265b73f0affc5d9bb8578`. Source investigation verified pinned +pnpm/action-setup readTarget uses path.join(GITHUB_WORKSPACE, packageJsonFile). +The existing lifecycle and macOS redaction assertions exposed real owner-side +defects; none will be removed or turned into warnings. + +### Local corrective evidence 2026-11-17 + +- Pinned upstream source confirms path.join(workspace, input). The new locator + resolves the Action's own canonical manifest to a relative input, validates its + exact packageManager pin, and handles distinct checkout/workspace directories. + Its contract reads the target with the same path.join operation while a consumer + has a deliberately different pin. Real exported consumer PASS with that locator. +- New real-host overlap regression failed before the service fix: [false,true] + instead of [true,true]. Per-root request queues and fresh snapshot objects now + publish only completed/non-disposed results. After-fix Electron: 7 PASS, + including the unchanged lifecycle assertion; 8 host-free unit tests PASS. +- Diagnostic helper now redacts declared and realpath aliases longest first. + Both exact failure/status/stdout assertions remain; a real directory link/ + junction test covers canonical output without depending on a machine path. +- Focused root contracts: 4 files / 32 PASS. Full root suite: 126 files PASS, + 774 PASS / 3 unchanged Windows privilege-dependent symlink skips (777 total). + Root lint/format/typecheck/build, schema regeneration/no drift, extension strict + lint/typechecks/build, cold Action consumer, offline and ACKit doctor/task doctor + and git diff --check PASS. No timeout, assertion or publish gate was weakened. +- Required hosted checks are still unproven for the successor commit. This task + remains active until the new exact-head matrix/Action/extension checks pass; + no old run will be rerun. No publication or tag action has occurred. + +Dependencies: TASK-0102 diff --git a/docs/tasks/archive/TASK-0098-action-threshold-and-self-contained-source-distr.md b/docs/tasks/archive/TASK-0098-action-threshold-and-self-contained-source-distr.md new file mode 100644 index 00000000..fbcd9996 --- /dev/null +++ b/docs/tasks/archive/TASK-0098-action-threshold-and-self-contained-source-distr.md @@ -0,0 +1,114 @@ +--- +id: "TASK-0098" +title: "Action threshold and self-contained source distribution" +status: completed +schemaVersion: 2 +dependencies: + [] +createdAt: "2026-11-17" +completedAt: 2026-11-17 +--- + + +## Purpose + +Restore reliable Action threshold enforcement and make a clean tag consumable +without pre-existing ignored build output. User authorized this repository audit, +local changes, tests, commits, branch pushes and PRs on 2026-11-17. + +## Scope + +- Confirmed: the tracked handwritten `dist/action/index.js` overwrites a threshold + failure with CLI status 0. No Action TypeScript source exists, and the referenced + CLI/runtime dependencies are absent from Git tags. +- Move the owning runtime to strict TypeScript; preserve the existing inputs, + outputs, read-only status/drift projection, annotations and optional SARIF. +- Use a source-built composite bootstrap under ADR-0034: pinned Node/pnpm actions, + frozen dependency install and build in the action checkout, then offline CLI + execution against the consumer. Do not commit generated `dist`. +- Preserve nonzero CLI errors, ignore policy-suppressed findings when applying the + Action threshold, reject invalid threshold/input syntax, and bound child execution. + +## Out of scope + +- Changing CLI/SDK contracts, release ordering, telemetry, automatic SARIF upload, + unrelated architecture, legacy .NET artifacts or credentials. + +## Affected files + +- `action.yml`, `src/action/**`, tracked legacy Action entry, Action contracts, + projection tests, offline gates, `.github/workflows/ackit-action-dogfood.yml`, + `docs/guides/ci.md`, ADR-0034 and decision index. + +## Dependencies + +None. Successor TASK-0099 starts after local acceptance is verified and committed. + +## Required tests + +- Focused Action behavior/security/consumer tests; projection and composition + parity; `pnpm lint`, `format:check`, `typecheck`, `build`, `test`; + offline-egress, ACKit doctor/task doctor/scan and `git diff --check`. + +## Acceptance criteria + +- [x] Threshold breach fails; below-threshold and suppressed findings pass; + CLI nonzero/invalid input/timeout errors remain failures. +- [x] Optional SARIF is canonical 2.1.0 with actual package identity and valid + relative locations; outputs exist only when their files exist. +- [x] Clean exported Action source installs/builds separately from an unrelated + consumer fixture and scans it without consumer dependencies or build output. +- [x] Dogfood exercises the bootstrap without a preparatory build; focused and + affected full tests plus quality/offline/ACKit checks pass. + +## Test steps + +1. Reproduce old exit-code overwrite and missing clean-tag runtime from inspected + source; record the exact change and regression results. +2. Exercise real CLI scan on clean/breaching/suppressed fixtures and a CLI usage + failure. Validate SARIF shape and injection-safe argv handling. +3. Export tracked/planned source into an isolated action checkout, frozen-install + and build it, execute from a separate Git fixture, then run affected full gates. + +## Security considerations + +Bootstrap dependency download is a workflow setup operation, not product egress. +Only trusted Action source and frozen lockfile may build; never execute consumer +scripts. Inputs cross through environment variables and argv, never shell code. +No secrets, permission changes, data migrations or production operations. + +## Risks + +- Bootstrap needs registry connectivity and adds setup cost. Document it; runtime + remains offline. Preserve existing public Action behavior and canonical outputs. + +## Rollback plan + +Forward corrective PR for the focused commits; immutable tags remain untouched. +No reset, rebase, force push or release mutation is authorized. + +## Completion notes + +Verified 2026-11-17 on Windows / Node 26.13.1 / pinned pnpm 11.22.0. + +- Root cause confirmed in the old tracked handwritten entry: after setting + threshold failure to 1, `result.status` reset it to 0. The entry also depended + on ignored CLI files absent from a tag. Strict owning source now builds both + entries, preserves CLI nonzero codes, and filters suppressed threshold inputs. +- The canonical SARIF writer replaces the divergent hand-built report (which + hardcoded an old tool version). Output/annotation/timeout/input regressions + are covered. The tracked legacy `dist` entry is removed from Git; generated + outputs stay ignored. +- `pnpm run smoke:action` PASS: clean exported source, independent frozen install + and build, unrelated consumer with no dependencies/dist, high threshold 0, + low threshold 1, CLI invalid-option 2, SARIF 2.1.0 and source-version parity. +- Focused Action/projection/composition/offline tests: 5 files, 29 tests PASS. + Full `pnpm test --maxWorkers=2`: 118 files PASS; 735 tests PASS, 3 existing + platform-conditional symlink tests skipped (Windows privilege probe). +- `pnpm lint`, `pnpm format:check`, `pnpm typecheck`, `pnpm build`, offline-egress + (203 files), doctor, task doctor, `scan --ci` (exit 0), text hygiene and + `git diff --check` PASS. No new unsuppressed High/Critical finding. +- Dogfood contract proves no preparatory install/build; hosted exact-head + execution and the OS/Node matrix are explicit TASK-0103 release prerequisites. +- No data migration, credential, permission or publication action. Successor: + TASK-0099 (CI/extension gates). Forward PR correction is the rollback path. diff --git a/docs/tasks/archive/TASK-0099-ci-extension-gates-schema-drift-and-artifact-int.md b/docs/tasks/archive/TASK-0099-ci-extension-gates-schema-drift-and-artifact-int.md new file mode 100644 index 00000000..2ba21bda --- /dev/null +++ b/docs/tasks/archive/TASK-0099-ci-extension-gates-schema-drift-and-artifact-int.md @@ -0,0 +1,136 @@ +--- +id: "TASK-0099" +title: "CI extension gates schema drift and artifact integrity" +status: completed +schemaVersion: 2 +dependencies: + - "TASK-0098" +createdAt: "2026-11-17" +completedAt: 2026-11-17 +--- + + +## Purpose + +Make every extension validation failure visible to CI and keep schema, version, +CLI/package consumer and VSIX integrity gates effective across patch releases. +User authorized scoped changes, tests, commits, branch pushes and PRs on 2026-11-17. + +## Scope + +- Confirmed CI masks extension lint, unit and Electron failures with shell + fallbacks, and hardcodes the source version/VSIX filename. +- Remove bypasses and correct underlying lint/test defects. Add usable extension + scripts and narrowly scoped formatting configuration if necessary. +- Pre-implementation inspection also found fabricated Electron assertions, + standalone unit tests importing the host-only `vscode` module, CommonJS + bundling of SDK `import.meta.url` asset lookups, and string-prefix finding path + checks. Replace these with real host/data assertions, a tested pure diagnostic + boundary, and a resource-aware bundle without changing the public SDK. +- The first real host run then proved an SDK defect: `scanRepository` documents + built-in rules plus optional extra rules but passes only `extraRules` (empty by + default) to the pipeline. Restore the existing built-in contract with a focused + SDK regression before rerunning extension tests; this is required for real + extension findings and remains backward-compatible with the documented API. +- Add schema drift and CLI smoke to CI; preserve real-tarball consumer smoke. +- Derive extension version from manifests, strengthen parity guard and packaged + VSIX inspection, and keep release security gates and Marketplace-first order. + +## Out of scope + +- Dependency upgrades, permission or protection changes, workflow dispatch/rerun, + release publication and unrelated extension UI redesign. + +## Affected files + +- `.github/workflows/ci.yml`, extension scripts/source/tests/configuration as + required by real failures, extension build/resource metadata, parity + scripts/contracts and VSIX integrity checks. +- `src/api/scan-repository.ts` and focused SDK scanning tests for the observed + missing-catalog defect; no new API or dependencies. + +## Dependencies + +TASK-0098. TASK-0100 follows this task. + +## Required tests + +- Root lint/format/typecheck/build/test, schema drift, CLI/package smokes; + extension typecheck/lint/unit/Electron/build; VSIX package/content checks; + workflow contracts, version parity, offline-egress and ACKit gates. + +## Acceptance criteria + +- [x] Lint, unit and Electron commands propagate real failures with no bypass. +- [x] Extension source/test typechecks and lint/unit/Electron tests actually pass. +- [x] CI has schema drift, CLI/package smoke, version parity and VSIX integrity + checks; source version and package filename are derived, not release literals. +- [x] VSIX manifest/README/CHANGELOG identity, file allowlist, size and secret + checks pass; release fail-closed gates remain effective. +- [x] Bundled SDK version/templates load inside the extension host and finding + navigation/diagnostics cannot resolve traversal or sibling-prefix paths. + +## Test steps + +1. Run the unmasked extension checks and fix observed failures, recording counts. +2. Add workflow contracts that reject suppressed exit codes and missing checks; + test version-parity negative probes against dynamic workflow configuration. +3. Package an actual VSIX and inspect packaged content, then run affected gates. + +## Security considerations + +No credential, data, migration or permission changes. Preserve strict types and +all existing publish gates. Electron uses a disposable local workspace. + +## Risks + +- Previously hidden failures may require focused source/test fixes. Preserve + assertions and validate Electron behavior in an actual VS Code host. + +## Rollback plan + +Forward corrective PR; no weakening checks, history rewriting or tag changes. + +## Completion notes + +Verified 2026-11-17; source/extension remain at the existing 0.5.4 during audit. + +- Removed all three CI exit-code fallbacks. Added schema drift, CLI smoke and + dynamic source/extension/VSIX parity gates; the existing real-tarball jobs stay. + Pinned packaging/probes to published vsce 4.1.1. Release retains every original + preflight, absence, Marketplace-first, npm OIDC and immutable-artifact gate; + the portable VSIX audit is an additional pre-publish check. +- Unmasked lint initially failed (4 errors/2 warnings). The old standalone unit + suite required host-only `vscode` and the Electron suite contained unconditional + assertions/catches. Production diagnostic/path logic now has 8 passing host-free + tests; Electron has 6 passing real data/command/diagnostic/lifecycle tests on + VS Code 1.146.0 (exit 0). No test failure fallback or disabled assertion remains. +- Host tests exposed SDK's empty default rule list, now restored to built-ins + plus extras. SDK scan/cancellation tests: 6 PASS. Initial runtime packaging + errors were corrected through the real host; the final bundled SDK identity, + templates and readiness calculation pass. Finding paths reject traversal, + sibling prefixes and escaping directory links, with real filesystem tests. +- Source maps were actually found in the first VSIX because the old ignore + matched only top-level maps. `**/*.map` now excludes them. Final audited VSIX: + 31 entries, 375515 bytes, SHA-256 + `ac731ccd09af55f23726dd7a16d329118e3ceefcd97bc5027a44fb0effadc2fd`. + Manifest/XML/SDK/README/CHANGELOG, profiles/roles, icon, path/file list, ZIP + bounds/CRC, size and credential-material checks PASS. Seven gate contracts + reject version/resource drift, unexpected files, actual synthetic key/token + material and payload corruption; detector header text is correctly accepted. +- Focused workflow/version/VSIX/SDK suites: 5 files / 69 tests PASS. + Full `pnpm test --maxWorkers=2`: 120 files PASS; 745 tests PASS, 3 unchanged + Windows privilege-dependent symlink skips. The full suite also exercises + isolated real-tarball consumers. +- Root lint/format/typecheck/build, extension source/test typechecks/lint/build, + schema generation with zero drift, CLI smoke, version parity, offline-egress + (204 files), text hygiene, doctor/task doctor, `scan --ci` exit 0 and + `git diff --check` PASS. No suppression/baseline or permission change. +- Separate audit discovery: registry audit of unchanged production dependencies + returns 40 advisories (1 critical/11 high). Dependency remediation belongs to + the preplanned TASK-0101 audit, outside this task's explicit no-upgrade scope; + TASK-0102/0103 cannot release without its disposition and verification. +- Successor TASK-0100: MCP schema/reference/CI hint parity. Hosted CI remains a + TASK-0103 prerequisite; no publication, tag or remote push occurred here. + +Dependencies: TASK-0098 diff --git a/docs/tasks/archive/TASK-0100-mcp-schema-documentation-and-ci-hint-parity.md b/docs/tasks/archive/TASK-0100-mcp-schema-documentation-and-ci-hint-parity.md new file mode 100644 index 00000000..3c45a489 --- /dev/null +++ b/docs/tasks/archive/TASK-0100-mcp-schema-documentation-and-ci-hint-parity.md @@ -0,0 +1,103 @@ +--- +id: "TASK-0100" +title: "MCP schema documentation and CI hint parity" +status: completed +schemaVersion: 2 +dependencies: + - "TASK-0099" +createdAt: "2026-11-17" +completedAt: 2026-11-17 +--- + + +## Purpose + +Align the documented read-only MCP contract with actual schemas and give the +advertised `ackit_scan.ci` option CLI-compatible exit hint semantics. +Scoped edits/tests/commits/PRs are user-authorized (2026-11-17). + +## Scope + +- Confirmed: docs advertise removed `root` and `includeGlobs` arguments; `ci` is + accepted but unused, so report-only scans hint failure as if CI was requested. +- Correct documentation without reopening root overrides or arbitrary file + inclusion. Wire `ci` to the advisory exit hint while retaining report content. +- Add schema/documentation and real-fixture behavioral contracts. +- Startup inspection also confirmed that CLI `--root` is accepted globally but + the MCP side-effect entry ignores it. Bind only the startup root through an + explicit stdio serve function; preserve ACKIT_ROOT/cwd fallbacks and never add + a per-tool root override. Verify precedence via real CLI stdio clients. + +## Out of scope + +- New tools, write capabilities, SDK upgrades, changed root/security boundaries, + transport redesign and broader error-format changes. + +## Affected files + +- `src/mcp/server.ts`, `docs/reference/mcp.md`, MCP contract/integration tests. +- `src/mcp/stdio.ts`, CLI MCP registration and startup-root integration tests. + +## Dependencies + +TASK-0099. TASK-0101 follows this task. + +## Required tests + +- MCP conformance, stdio, cancellation, root-boundary and cross-surface tests; + root lint/format/typecheck/build/full tests; offline and ACKit gates. + +## Acceptance criteria + +- [x] Docs list precisely the tool input properties; no per-call root or pack + includeGlobs is reintroduced. +- [x] Report-only scan hints 0, `ci: true` hints 1 only for unsuppressed findings + at the configured threshold; clean/suppressed cases hint 0. +- [x] Cancellation, stdio purity, root confinement and CLI/SDK/MCP parity pass. + +## Test steps + +1. Compare live `tools/list` schemas to the reference table in a contract test. +2. Call scan with default/false/true CI on real clean/breaching/suppressed fixtures. +3. Run MCP/security/parity subsets followed by the affected full gates. + +## Security considerations + +No network/write capability, data migration or permission change. The server +continues to bind a canonical root once at construction. The hint is advisory; +tool calls never terminate the server process. + +## Risks + +- Consumers relying on the incorrect default hint must request `ci: true`; + document this patch correction. No argument removal from the actual API. + +## Rollback plan + +Forward corrective PR limited to MCP implementation/docs/tests; no tag changes. + +## Completion notes + +Verified 2026-11-17 on Windows / Node 26.13.1 / pnpm 11.22.0. + +- Actual `tools/list` properties for all 16 tools now match the reference table. + The docs no longer advertise per-call root or pack includeGlobs. No removed + security-sensitive input was restored. +- `ci` was accepted but unused. Default/false scans now hint 0; true hints 1 at + an unsuppressed policy threshold and 0 for clean/suppressed fixtures. Reports + remain available, the hint is advisory, and the server stays responsive. +- CLI accepted global `--root` but imported a side-effect entry that read only + environment/cwd. An explicit stdio serve function now receives the startup + root. Real CLI stdio clients prove flag-over-environment, environment-over-cwd + and cwd fallback, with paths containing spaces. Direct stdio entry still works. +- MCP/stdio/cancellation/status projection suites: 7 files, 30 tests PASS. + Filesystem/adversarial boundary subset: 23 PASS / 2 existing privilege skips. + Final full `pnpm test --maxWorkers=2`: 122 files PASS; 754 PASS / 3 unchanged + Windows privilege-dependent symlink skips (757 total). +- `pnpm lint`, `format:check`, `typecheck`, `build`, offline-egress, doctor, + task doctor, `scan --ci` exit 0 and `git diff --check` PASS. +- No public SDK export change, new tool, network/write capability, data migration, + permission or publication action. Successor TASK-0101 owns docs/portability and + the already identified dependency-security audit. Forward PR is rollback. + +Dependencies: TASK-0099 diff --git a/docs/tasks/archive/TASK-0101-documentation-task-integrity-portability-and-cro.md b/docs/tasks/archive/TASK-0101-documentation-task-integrity-portability-and-cro.md new file mode 100644 index 00000000..56fa3f6d --- /dev/null +++ b/docs/tasks/archive/TASK-0101-documentation-task-integrity-portability-and-cro.md @@ -0,0 +1,151 @@ +--- +id: "TASK-0101" +title: "Documentation task integrity portability and cross-surface audit" +status: completed +schemaVersion: 2 +dependencies: + - "TASK-0100" +createdAt: "2026-11-17" +completedAt: 2026-11-17 +--- + + +## Purpose + +Audit maintained documentation, task integrity and runtime boundaries; fix +verified scoped defects while preserving historical evidence. User authorized +necessary edits, tests, commits and PRs on 2026-11-17. + +## Scope + +- Check README links, Docs7 routes/schema, Context7 config, ADR references and + live task IDs versus the frozen legacy namespace. Preserve legacy task files. +- Reconcile TASK-0097 with actual repository/CI/external hosting evidence; close + and archive only if every literal acceptance criterion passes. +- Inspect machine-specific fixtures, cross-surface exit contracts, cancellation, + bounded processes, filesystem/traversal/secret boundaries, dependencies, + offline behavior and packaging. Fix confirmed in-scope defects with tests. +- Registry audit on 2026-11-17 found 40 advisories in the unchanged production + graph (1 critical/11 high). Inspect primary advisory ranges and reachability; + perform only necessary compatible security updates (SDK 1.x, Zod 4.x and + affected transitives), with frozen lockfile/schema/contract/runtime checks. + No major-version migration or indiscriminate dependency refresh. +- Record source-grounded findings and distinguish external validation gaps. + +## Out of scope + +- Rewriting historical ADR/task evidence; casually closing TASK-0087/0092/0093; + hosted account setup/deployment; speculative refactoring or unrelated dependency upgrades. + +## Affected files + +- README and maintained docs/configuration, task records, focused fixture/tests, + documentation checks; runtime files only for confirmed audit defects. +- Root package manifest/lockfile only for necessary audited dependency fixes; + regenerate schemas only if the validated generator actually changes them. +- `examples/sdk-consumer.mjs` and SDK reference signatures: inspection found + string roots where the actual scanner requires `{ canonicalPath }` and stale + rule-pack/readiness signatures. Verify the corrected example on a real fixture. + +## Dependencies + +TASK-0100. TASK-0102 follows; external Docs7 setup is not a patch-release prerequisite. + +## Required tests + +- Local link/route/config validation, documentation smoke, portability/security + and cross-surface tests, dependency audit, full affected gates and ACKit checks. + +## Acceptance criteria + +- [x] Maintained README links, docs routes, Context7 config and ADR references + resolve; active/archive task IDs are unique and legacy collisions explained. +- [x] Machine-specific test literals are either portable synthetic fixtures or + replaced; historical proof remains intact. +- [x] Audit results record exact evidence and no unresolved new High/Critical + finding remains in release scope. +- [x] TASK-0097 status reflects real evidence; incomplete external acceptance + stays explicitly blocked and historical blocked tasks remain unchanged. + +## Test steps + +1. Inspect current source/security tests and published documentation schemas. +2. Verify all maintained local links/routes and task namespace integrity; run + actual CLI documentation quickstart in a disposable fixture. +3. Run targeted boundary/portability/cancellation tests and dependency audit, + then affected full checks. Record any external hosting/account blocker. + +## Security considerations + +Use source review and existing defensive tests with synthetic fixtures; no live +attack probes, real secrets or production data. No permission/data migrations. +Do not change suppression rules or baselines merely to obtain a passing scan. + +## Risks + +- Historical root-level task IDs intentionally overlap the live TypeScript + namespace. External Docs7 ownership/build evidence may be unavailable. + +## Rollback plan + +Forward corrective PR; retain historical records and immutable release artifacts. + +## Completion notes + +Verified 2026-11-17 on Windows / Node 26.13.1 / pnpm 11.22.0. + +- Fixed 12 broken README link occurrences by pointing to existing owning + references/concepts/extension docs. All 32 Docs7 navigation routes resolve. + Checked ADR IDs across 30 maintained files: no unresolved reference. + Task store has 103 records / 103 unique live IDs; the new task README explains + the separate root-level historical namespace. No historical record was moved, + deleted, renumbered or falsely completed. +- The SDK example and cancellation snippet passed a path string to an API that + requires `{ canonicalPath }`. They now resolve a portable canonical root; + the real example runs on an unrelated one-file fixture and finds its marker. + Corrected rule-pack/readiness signatures, config-loading description and + overly broad cancellation claims without changing the public SDK API. +- Personal Windows profile literals in two content-only scanner fixtures became + `fixture-user`; they never accessed that path. Generic Windows drive/case + vectors remain intentionally synthetic. Maintained product docs/tests contain + no former machine-specific user/repository path. Historical evidence is intact. +- Registry production audit initially returned 40 advisories (1 critical, + 11 high). Necessary compatible updates: MCP SDK 1.30.0 -> 1.32.2, Zod 4.4.3 -> + 4.6.7 and affected SDK transitives. Direct dependency major versions and all + unrelated direct dependencies remain unchanged. Frozen install PASS. + `pnpm audit --prod --json` now exits 0, zero advisories at every severity. + Primary patch evidence: [SDK 1.32.2](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.32.2), + [Zod advisory](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5), + [proxy-addr advisory](https://github.com/advisories/GHSA-jqcg-44mw-7w3h). +- Full development-tool audit still exits 1: 19 pre-existing advisories + (6 high / 11 moderate / 2 low), confined to Mocha/glob/esbuild/Vitest/Vite + development paths, not the production graph or packaged VSIX runtime. + Mocha's serialize-javascript use is in its parallel worker pool; both harnesses + run serial TDD. No .mocharc YAML payload is supplied; glob patterns are fixed + test-discovery patterns. esbuild serves no development HTTP endpoint here; + Vitest runs without its API/UI and product code imports none of these tools. + Arbitrary major tool migrations are outside this patch; these metadata + advisories are disclosed, not suppressed or reported as a clean full audit. +- Zod regenerated three tracked schemas, replacing string/null anyOf branches + with equivalent type arrays. Recursive normalized comparison against HEAD + proved equivalence in all three; a second generation has no unstaged drift. +- Focused documentation/SDK/portable-pack/security/MCP/API suites: 11 files / + 48 tests PASS. Full suite: 124 files PASS; 758 tests PASS / 3 unchanged Windows + privilege-dependent symlink skips (761 total). Extension typechecks/lint/build, + 8 unit and 6 real Electron host tests PASS after the dependency update. + Audited VSIX: 31 entries / 414645 bytes / SHA-256 + `e24783d4a19ce45587e69f6a73fccd4b3f31d95e73a85517bf5cba7bab9e9e95`. +- Root lint/format/typecheck/build, schema stability, actual documentation + quickstart, version parity, offline-egress (204 files), config/doctor/task + doctor/skills (4 skills, 0 issues), `scan --ci` exit 0, text hygiene and + `git diff --check` PASS. Full-suite tarball consumers also PASS. +- Context7 validates against the downloaded official schema. The upstream + Docs7 schema has an unrelated invalid Unicode regex; production hosting, + endpoints and account verification are **Not run**. TASK-0097 records the + exact external gap and remains blocked. TASK-0087/0092/0093 stay untouched. +- No new confirmed High/Critical finding remains in the shipped/runtime scope. + No credentials, permissions, data migrations, deployment, tag or publication + action. Successor TASK-0102 prepares the compatible patch; hosted matrix and + final publication remain explicit TASK-0103 prerequisites. + +Dependencies: TASK-0100 diff --git a/docs/tasks/archive/TASK-0102-patch-release-preparation-and-full-validation.md b/docs/tasks/archive/TASK-0102-patch-release-preparation-and-full-validation.md new file mode 100644 index 00000000..1c4ce224 --- /dev/null +++ b/docs/tasks/archive/TASK-0102-patch-release-preparation-and-full-validation.md @@ -0,0 +1,147 @@ +--- +id: "TASK-0102" +title: "Patch release preparation and full validation" +status: completed +schemaVersion: 2 +dependencies: + - "TASK-0101" + - "TASK-0104" +createdAt: "2026-11-17" +completedAt: 2026-11-17 +--- + + +## Purpose + +Prepare the next compatible patch only after fixing and verifying the audit +chain. npm latest and Marketplace were both independently read as 0.5.4 on +2026-11-17, so the planned source version is 0.5.5 if no breaking change emerges. + +## Scope + +- Align source/extension manifests, lockfile if affected, source-facing README, + root/extension CHANGELOG and extension README/packaged metadata. +- Preserve `release-state.json.publishedStable = 0.5.4` and stable install pins + until TASK-0103 proves all public channels at the new version (ADR-0029). +- Execute the entire requested local verification matrix and audit VSIX/tarball. +- Record authorization, exact evidence, risks and release-ready decision. +- Correct the final read-only Marketplace visibility probe: TASK-0094 records + that the 0.5.4 release's last one-shot read saw a stale replica after successful + publication. Add bounded retries while requiring exact target visibility and + retaining exit 91 on exhaustion; no publish order, permission or gate changes. + +## Out of scope + +- Publication/tag creation before validation, dependency upgrades, speculative + source changes, changing historical version references or public stable early. + +## Affected files + +- Root/extension manifests and release docs, relevant lockfile metadata, task + evidence; ignored local packages/checksums are never tracked. +- `.github/workflows/release.yml` final visibility read and its focused workflow + contract, planned before implementing this demonstrated release-wrapper fix. + +## Dependencies + +TASK-0101 and TASK-0104. TASK-0103 requires all acceptance below and exact-head PR CI. + +## Required tests + +- Frozen install; lint/format/typecheck/build/gen:schemas/no drift; full tests; + CLI/package/doc smokes; config/doctor/task doctor/skills/instructions/scan; + extension typechecks/lint/unit/Electron/build/package; VSIX integrity; + Action clean-consumer, release/version parity, offline and text hygiene gates. + +## Acceptance criteria + +- [x] Source/extension/package docs are coupled at the next absent patch; + published-stable claims remain truthful until publication. +- [x] All required local checks pass with exact counts/commands recorded; + no skipped mandatory tests or unresolved release-scope security finding. +- [x] Actual tarball/VSIX audited, SHA-256 recorded and release notes reviewed. +- [x] Final diff and ACKit checks pass; all pre-release work is committed and + the tree is clean before an authorized push. + +## Test steps + +1. Recheck npm/Marketplace versions and target absence; couple source metadata. +2. Run the required checks with repository-pinned pnpm 11.22.0. Environment + preflight: PowerShell 7.6.9/Git 2.56.1/Node 26.13.1 work; broken global pnpm + 12.21.0 launchers are bypassed by an ignored isolated 11.22.0 toolchain. +3. Build/audit packages and record checksums, then review final diff/state. + +## Security considerations + +No secrets in outputs/artifacts; no data/migration/permission changes. User +explicitly authorized scoped commits, ordinary branch push and PR creation. +No workflow dispatch, rerun, deployment or direct master push is authorized. + +## Risks + +- Hosted Node 22/24 and Linux/macOS verification is required in TASK-0103; local + Windows Node 26 evidence alone never proves that matrix. Existing historical + blocked tasks retain their real status. + +## Rollback plan + +Forward corrective PR before release; never reuse or move immutable versions. + +## Completion notes + +Final local validation 2026-11-17, after TASK-0104 corrective verification: + +- Source/extension/packaged metadata 0.5.5; stable pointer/install pins remain + 0.5.4 as required by ADR-0029. npm/Marketplace both re-read 0.5.4; target npm + 0.5.5 returns E404 and remote v0.5.5 tag is absent. No breaking public SDK/CLI + export/argument removal. Source README build instructions now use the real + package selector and audited bundled VSIX command. +- Pinned pnpm 11.22.0 frozen install PASS; root lint, format, typecheck, build, + version 0.5.5 and schema generation/no drift PASS. Full current code suite: + 125 files PASS, 772 tests PASS / 3 unchanged Windows privilege-dependent + symlink skips (775 total). Release/version/tag/VSIX/docs subset also passed. +- CLI smoke, explicit real-tarball package consumer smoke, documentation command + smoke and clean Action source consumer PASS. The Action consumer now exercises + scan/optimize/drift thresholds, CLI error preservation, legacy no-op and + canonical CLI/Action optimize SARIF equality with no consumer runtime files. +- Final extension source/test typechecks, strict lint, build, 8 unit and 6 real + Electron host tests PASS at 0.5.5. An initial command batch used an incorrect + relative toolchain prefix; it was cancelled and not counted. The verified + root-cwd run explicitly reported pnpm 11.22.0 and all actual checks above. +- Audited artifacts in ignored `artifacts/release-0.5.5/`: + - `ackit-vscode-0.5.5.vsix`: 31 entries, 414975 bytes, SHA-256 + `8fa4cfc2f804f1440fcf1c5abe215570b7ee5c4c1762654a53676696c8d9fd9f`. + - `cynrath-agent-context-kit-0.5.5.tgz`: 497350 bytes, SHA-256 + `699437eff29c9dbd74ccd7104e2116ea1a384229cfb1b4e65cc49c88fa6b6a7f`. + Actual VSIX manifest/XML/SDK/README/CHANGELOG, templates, file list, icon, + bounded ZIP extraction/CRC, size and secret checks PASS. Local checksum file + contains filenames/hashes only. Extracted 0.5.5 release notes pass text hygiene. +- Production dependency audit: zero known advisories (TASK-0101 has the explicit + separate development-tool advisory disposition). Offline-egress, config, + doctor/task doctor, skills (4/0 issues), instructions, scan --ci (exit 0), + text hygiene, version parity and git diff --check PASS. +- Final Marketplace read now has six bounded attempts with exact target + comparison and exit 91 retained. Focused workflow contracts PASS; all original + publish-order/security/absence/OIDC/artifact gates remain. No dispatch/rerun, + permission, credential or deployment action. +- Final diff reviewed. The implementation/evidence commit and clean-tree proof + are the remaining Git criterion before completion. Hosted OS/Node matrix, + protected PR merge and all publication actions belong to TASK-0103. + +Git criterion verified: implementation/evidence commit +`eae5351fd3df07106a83a8bb12935241ed69f8bd` exists and `git status --short --branch` +shows only the branch header (clean tree). All pre-release implementation is +committed before any push. This closure record follows the observed proof. + +### Dependency checkpoint 2026-11-17 + +Source/extension metadata is coupled at 0.5.5, stable remains 0.5.4, npm target +and remote tag are absent. The versioned full suite passed 758 tests (3 unchanged +Windows privilege skips), extension 8 unit/6 Electron tests passed, and the final +visibility-read contract passed. The actual clean Action consumer then failed +at frozen install with an opaque diagnostic; source review also found optimize +suggestions omitted from Action threshold projection. TASK-0104 owns corrective +verification before this task resumes final checks. All working changes remain +preserved. No push, tag, PR merge or publication has occurred. + +Dependencies: TASK-0101 diff --git a/docs/tasks/archive/TASK-0104-action-optimize-projection-and-cold-consumer-cor.md b/docs/tasks/archive/TASK-0104-action-optimize-projection-and-cold-consumer-cor.md new file mode 100644 index 00000000..857d89a6 --- /dev/null +++ b/docs/tasks/archive/TASK-0104-action-optimize-projection-and-cold-consumer-cor.md @@ -0,0 +1,152 @@ +--- +id: "TASK-0104" +title: "Action optimize projection and cold consumer corrective verification" +status: completed +schemaVersion: 2 +dependencies: + - "TASK-0101" +createdAt: "2026-11-17" +completedAt: 2026-11-17 +--- + + +## Purpose + +Correct the final-audit gaps in the Action's advertised optimize command and +clean-consumer bootstrap before TASK-0102/0103 may proceed. Scoped edits, tests, +commits and PR work are authorized by the 2026-11-17 goal. + +## Scope + +- Confirmed source gap: the typed Action wrapper reads only report.findings, + while CLI optimize emits report.suggestions; its severity threshold is ignored. +- Restore optimize projections without changing the original JSON report or + scanner behavior. Reuse the canonical SARIF writer with source suggestion IDs, + severities and relative locations; do not invent a parallel report format. +- The same scanner-only validation rejects advertised `drift check` findings + (`code/detail`, blocking/warning). Add its explicit projection, preserving raw + JSON and CLI codes; map blocking to high and warning to medium for Action + thresholds. Global task drift has no invented file location in SARIF. +- The shared SARIF writer currently emits raw path characters. Encode URI path + segments for spaces, fragment/query characters and Unicode per SARIF 2.1.0 + section 3.10.4, preserving path separators and the existing report contract. +- CLI optimize has its own raw-path SARIF construction. Route that existing + format through the same typed suggestion projection and canonical writer, so + CLI and Action reports stay semantically identical and URI-safe. +- The real clean-consumer smoke failed at its frozen install with an empty error + because the helper reads only stderr. Surface safe stdout/error/status details, + diagnose the actual bootstrap failure, and fix its source contract without + bypassing frozen install, build or process exit checks. +- Extend focused and actual consumer regressions for optimize and bootstrap. + +## Out of scope + +- New public CLI/SDK features, untrusted rule execution, network in product code, + unrelated dependency upgrades, publication, permission or credential changes. + +## Affected files + +- `src/action/runtime.ts`, canonical SARIF input typing if required, + `tests/unit/action/runtime.test.ts`, Action distribution contracts, + `scripts/action-consumer-smoke.mjs`, `action.yml` only if the observed bootstrap + contract requires correction, and affected CI guide/task evidence. +- `src/cli/commands/optimize.ts` for its existing SARIF format only; JSON and + business logic remain unchanged. +- A small adjacent consumer-command helper to isolate real subprocess diagnostic + testing from the expensive repository export/install fixture. The first full + run had 771 passes/1 failure: the diagnostic test ended with empty stderr + before its expected marker, while focused/real consumer checks passed. Test + the same actual failing child/status/stdout/redaction boundary directly; do + not raise timeouts, remove assertions or skip the full consumer check. + +## Dependencies + +TASK-0101 (including TASK-0098). TASK-0102 is temporarily pending on this task; +its existing version/docs/workflow changes are preserved on the same branch. + +## Required tests + +- Action/scanner/SARIF/parity contracts, real clean-source consumer including + optimize; lint/format/typecheck/build and affected full tests; offline/ACKit + doctor/task doctor/scan and `git diff --check`. + +## Acceptance criteria + +- [x] Optimize above/below-threshold and CLI-error cases return correct codes; + original JSON remains unchanged and canonical SARIF has source IDs/locations. +- [x] Real exported source frozen-installs and builds, then scan/optimize work + from an independent repository with no consumer dependencies/dist. +- [x] A failed consumer command reports a useful sanitized status/cause and + remains a hard failure; no frozen/build/threshold test is skipped or masked. +- [x] SARIF artifact URIs encode reserved/Unicode path characters correctly. +- [x] Nonempty drift reports remain available, with documented severity mapping + and valid location-free SARIF results for task-level findings. +- [x] Focused/full affected quality, offline and ACKit checks pass with evidence. + +## Test steps + +1. Add the optimize regression and record its failure against the current wrapper. +2. Improve only the consumer diagnostic, reproduce its frozen-install failure, + then fix the verified cause at the owning bootstrap/export surface. +3. Validate optimize JSON/SARIF/thresholds and rerun the actual clean-consumer flow. +4. Run affected full gates; record real results before completion/commit, then + immediately resume TASK-0102's final release preparation. + +## Security considerations + +No environment/credential dump. Redact scratch/source paths in diagnostics. +Only trusted Action source is installed/built; never consumer scripts. Preserve +offline execution, injection-safe argv, policy suppression and nonzero CLI codes. +No data migration, deployment, tag or publication operation. + +## Risks + +- Suggestions differ from scanner findings; projection must preserve their + category/identity without weakening scanner schema validation. +- A bootstrap failure may be environmental; distinguish it using observed output + rather than assuming a repository or dependency defect. + +## Rollback plan + +Forward corrective PR/commit only; preserve all existing work and immutable tags. + +## Completion notes + +Verified 2026-11-17 on Windows / Node 26.13.1 / pnpm 11.22.0. + +- Before-fix optimize regression: expected exit 1, actual 0. Typed projections + now handle scanner findings, optimize suggestions and drift code/detail data + while preserving original JSON. Scan schemas remain strict; missing expected + arrays fail closed. CLI nonzero codes win over threshold results. +- Drift blocking/warning map to high/medium only in the Action projection. + Task-level SARIF omits invented file locations; check-active's successful + silent legacy no-op is preserved. CLI optimize and Action share one canonical + SARIF suggestion projection/writer. Reserved/Unicode path segments are encoded. +- Real clean export/frozen install/build/independent consumer PASS repeatedly + at 0.5.5: scan/optimize/drift above/below thresholds, actual invalid-option + CLI errors, legacy no-op, original reports, and CLI/Action optimize SARIF + equality. Consumer supplies no node_modules or dist. +- The initial opaque install failure was not reproduced; original stdout was + unavailable, so no source/environment root cause is invented. Frozen/build + gates were unchanged. A bounded process helper now includes stdout/error/status + and sanitizes source/fixture paths. Its real failing-child test asserts exact + outer exit 1, inner exit 7, stdout cause and path redaction. +- First full run: 771 PASS / 1 diagnostic-test failure (empty stderr before its + expected marker) / 3 existing skips. The diagnostic boundary was isolated from + unnecessary full repository export; no timeout was raised and no assertion + or consumer gate was removed. Final full run: 125 files PASS; 772 tests PASS, + 3 unchanged Windows privilege-dependent symlink skips (775 total). +- Focused Action/diagnostic/reporting/projection/drift suites: 5 files / 36 PASS. + Root lint, format, typecheck, build, doctor/task doctor, scan --ci (exit 0), + offline-egress and git diff --check PASS. A transient Windows Biome file-mapping + write error cleared on the explicit rerun; final lint/format passed normally. +- Actual scan/optimize/drift SARIF documents validate against both current + [OASIS 2.1.0 errata schema](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json) + and the producer-declared SchemaStore schema, with standard format validation. + A deliberately invalid URI was rejected by both. No provider schema was edited + and URI checks remained enabled. +- No new public SDK export, dependency, network/runtime capability, credential, + permission, deployment, tag or publication change. Forward corrective commit + is rollback. Resume TASK-0102 immediately, preserving its metadata/workflow work. + +Dependencies: TASK-0101 diff --git a/examples/sdk-consumer.mjs b/examples/sdk-consumer.mjs index 3e701c78..c719c846 100644 --- a/examples/sdk-consumer.mjs +++ b/examples/sdk-consumer.mjs @@ -1,10 +1,11 @@ #!/usr/bin/env node +import { realpath } from "node:fs/promises"; // Minimal SDK consumer smoke (ESM) โ€” documented in docs/reference/sdk.md // Run: node examples/sdk-consumer.mjs (or after `pnpm pack` install via `node -e "import(...)"`) import { scanRepository } from "@cynrath/agent-context-kit"; -const root = process.cwd(); +const root = { canonicalPath: await realpath(process.cwd()) }; const result = await scanRepository(root, {}); console.log(`sdk-consumer: findings=${result.findings.length} filesScanned=${result.filesScanned}`); -if (result.findings.length === 0) console.log("no findings (repo may be clean or suppressed)"); +if (result.findings.length === 0) console.log("no findings"); // No process.exit from SDK โ€” CLI layer owns exit codes diff --git a/extensions/vscode/.vscodeignore b/extensions/vscode/.vscodeignore index 3ee8d94b..e89a63a9 100644 --- a/extensions/vscode/.vscodeignore +++ b/extensions/vscode/.vscodeignore @@ -3,10 +3,13 @@ src/** node_modules/** out/** +scripts/** +test-fixture/** +*.vsix .gitignore .eslintrc* -tsconfig.json +tsconfig*.json webpack.config.js -*.map +**/*.map **/*.ts !dist/extension.js diff --git a/extensions/vscode/CHANGELOG.md b/extensions/vscode/CHANGELOG.md index 024c6e5e..955d9070 100644 --- a/extensions/vscode/CHANGELOG.md +++ b/extensions/vscode/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog โ€” VS Code Extension +## [0.5.5] - 2026-11-17 + +- Restored built-in SDK scanning so repository markers and security findings + appear in the Findings tree and Problems diagnostics. +- Bundled SDK identity and built-in profiles/roles resolve inside the packaged + extension; readiness now works without relying on checkout files. +- Finding navigation and diagnostics reject traversal, sibling-prefix paths and + directory links escaping the workspace. +- Overlapping watcher/manual refreshes are serialized per root, so explicit + refresh commands return a completed current scan rather than cancelled stale data. +- Real host-free unit and Electron data/command/lifecycle tests are enforced in CI; + VSIX packaging excludes source maps and verifies manifest/README/CHANGELOG parity. +- Compatible runtime security dependency updates; offline analysis and existing + commands/views remain unchanged. Version coupled to the root package at 0.5.5. + ## [0.5.4] - 2026-09-22 - Recovery: no extension UI behavior change beyond 0.5.3; manifest diff --git a/extensions/vscode/README.md b/extensions/vscode/README.md index 8fbe19b0..94efc546 100644 --- a/extensions/vscode/README.md +++ b/extensions/vscode/README.md @@ -3,7 +3,7 @@ Offline-first agent readiness for your repository โ€” directly inside VS Code. - **Publisher:** `Cynrath` (`Cynrath.ackit-vscode`) -- **Version:** `0.5.4` (Marketplace stable; source checkouts build `0.5.4`) +- **Version:** `0.5.5` (extension release metadata; source checkouts build `0.5.5`) - **Engine:** `VS Code ^1.90.0` - **Activation:** `onStartupFinished` (debounced, lazy refresh) - **Category:** `Linters` diff --git a/extensions/vscode/package.json b/extensions/vscode/package.json index 7ea198fd..976f4685 100644 --- a/extensions/vscode/package.json +++ b/extensions/vscode/package.json @@ -2,7 +2,7 @@ "name": "ackit-vscode", "displayName": "ACKit Toolkit", "description": "Offline-first repository readiness, task status, verification-aware workflow and developer tooling for AI-assisted development in VS Code.", - "version": "0.5.4", + "version": "0.5.5", "publisher": "Cynrath", "engines": { "vscode": "^1.90.0" @@ -101,9 +101,12 @@ } }, "scripts": { - "build": "esbuild src/extension.ts --bundle --platform=node --target=node20 --outfile=dist/extension.js --external:vscode --sourcemap", + "build": "node scripts/build.mjs", + "lint": "biome check src scripts --error-on-warnings", + "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit", "compile:test": "tsc -p tsconfig.test.json", - "test": "npm run compile:test && node ./out/test/runTest.js", + "test:unit": "npm run compile:test && mocha --ui tdd out/test/suite/unit.test.js --timeout 5000", + "test": "node ./out/test/runTest.js", "pretest": "npm run compile:test" }, "devDependencies": { diff --git a/extensions/vscode/scripts/build.mjs b/extensions/vscode/scripts/build.mjs new file mode 100644 index 00000000..bdc732d5 --- /dev/null +++ b/extensions/vscode/scripts/build.mjs @@ -0,0 +1,54 @@ +import { cp, mkdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { build } from "esbuild"; + +const extensionRoot = fileURLToPath(new URL("../", import.meta.url)); +const repoRoot = path.resolve(extensionRoot, "../.."); +const sdkSource = path.join(repoRoot, "src"); +const output = path.join(extensionRoot, "dist"); +const pkg = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8")); +await mkdir(output, { recursive: true }); + +await build({ + absWorkingDir: extensionRoot, + entryPoints: ["src/extension.ts"], + bundle: true, + platform: "node", + target: "node20", + format: "cjs", + outfile: "dist/extension.js", + external: ["vscode"], + sourcemap: true, + banner: { + js: '"use strict";\nconst __ackitBundleModuleUrl = (relative) => require("node:url").pathToFileURL(require("node:path").join(__dirname, "sdk", relative)).href;', + }, + plugins: [ + { + name: "bundled-sdk-resources", + setup(builder) { + builder.onResolve({ filter: /^@cynrath\/agent-context-kit$/ }, () => ({ + path: path.join(sdkSource, "index.ts"), + })); + builder.onLoad({ filter: /\.ts$/ }, async ({ path: file }) => { + const relative = path.relative(sdkSource, file); + if (relative.startsWith("..") || path.isAbsolute(relative)) return; + const source = await readFile(file, "utf8"); + if (!source.includes("import.meta.url")) return; + // Preserve canonical module-relative asset lookup inside a CommonJS + // bundle. Embed only package-relative paths, never build-machine paths. + const virtualPath = JSON.stringify(relative.split(path.sep).join("/")); + const moduleUrl = `__ackitBundleModuleUrl(${virtualPath})`; + return { contents: source.replaceAll("import.meta.url", moduleUrl), loader: "ts" }; + }); + }, + }, + ], +}); +// SDK modules resolve package.json/templates from this bundled package root. +await writeFile( + path.join(output, "package.json"), + `${JSON.stringify({ name: pkg.name, version: pkg.version }, null, 2)}\n`, +); +await cp(path.join(repoRoot, "templates"), path.join(output, "templates"), { recursive: true }); +console.log(`Extension bundle PASS (${pkg.version}; SDK identity and templates included)`); diff --git a/extensions/vscode/src/diagnostics.ts b/extensions/vscode/src/diagnostics.ts new file mode 100644 index 00000000..28a69db4 --- /dev/null +++ b/extensions/vscode/src/diagnostics.ts @@ -0,0 +1,35 @@ +import { realpathSync } from "node:fs"; +import path from "node:path"; + +export function diagnosticKind(severity: string): "Error" | "Warning" | "Information" | "Hint" { + if (severity === "critical" || severity === "high") return "Error"; + if (severity === "medium") return "Warning"; + if (severity === "low") return "Information"; + return "Hint"; +} + +/** Findings may only address existing files inside the canonical workspace. */ +export function resolveFindingPath(root: string, relativePath: string): string | null { + if ( + !relativePath || + relativePath.includes("\0") || + path.win32.isAbsolute(relativePath) || + path.posix.isAbsolute(relativePath) + ) + return null; + try { + const canonicalRoot = realpathSync(root); + const full = realpathSync(path.resolve(canonicalRoot, relativePath.replaceAll("\\", path.sep))); + const relative = path.relative(canonicalRoot, full); + if ( + !relative || + relative === ".." || + relative.startsWith(`..${path.sep}`) || + path.isAbsolute(relative) + ) + return null; + return full; + } catch { + return null; + } +} diff --git a/extensions/vscode/src/extension.ts b/extensions/vscode/src/extension.ts index 6e35568d..f02498ca 100644 --- a/extensions/vscode/src/extension.ts +++ b/extensions/vscode/src/extension.ts @@ -3,10 +3,9 @@ import { analyzeOptimize, buildInstructionGraph, resolveEffectiveStack, - scanRepository, - scoreRepository, } from "@cynrath/agent-context-kit"; import * as vscode from "vscode"; +import { diagnosticKind, resolveFindingPath } from "./diagnostics.js"; import { AckitWorkspaceService } from "./services/ackitWorkspace.js"; let service: AckitWorkspaceService | undefined; @@ -398,11 +397,8 @@ export async function activate(context: vscode.ExtensionContext) { service?.getSnapshot()?.root ?? vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? ""; if (!root) continue; // Only create diagnostics for files that are inside workspace - const full = path.isAbsolute(f.relativePath) - ? f.relativePath - : path.join(root, f.relativePath); - // Ensure inside root - if (!full.startsWith(root)) continue; + const full = resolveFindingPath(root, f.relativePath); + if (full === null) continue; uri = vscode.Uri.file(full); } catch { continue; @@ -411,14 +407,7 @@ export async function activate(context: vscode.ExtensionContext) { const col = Math.max(0, (f.column ?? 1) - 1); // Handle invalid line/col: if 0, use 0,0 range const range = new vscode.Range(line, col, line, col + 10); - const severity = - f.severity === "critical" || f.severity === "high" - ? vscode.DiagnosticSeverity.Error - : f.severity === "medium" - ? vscode.DiagnosticSeverity.Warning - : f.severity === "low" - ? vscode.DiagnosticSeverity.Information - : vscode.DiagnosticSeverity.Hint; + const severity = vscode.DiagnosticSeverity[diagnosticKind(f.severity)]; const diag = new vscode.Diagnostic(range, f.message, severity); diag.code = f.ruleId; diag.source = "ackit"; @@ -450,6 +439,7 @@ export async function activate(context: vscode.ExtensionContext) { const roots = service?.getRoots() ?? []; for (const r of roots) await service?.refreshRoot(r); vscode.window.showInformationMessage(`ACKit: refreshed ${roots.length} workspace(s)`); + return service?.getSnapshot(); }), vscode.commands.registerCommand("ackit.showGraph", async (nodeId?: string) => { const snap = service?.getSnapshot(); @@ -502,7 +492,8 @@ export async function activate(context: vscode.ExtensionContext) { vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? ""; if (!root) return; - const full = path.join(root, finding.relativePath); + const full = resolveFindingPath(root, finding.relativePath); + if (full === null) return; const uri = vscode.Uri.file(full); const doc = await vscode.workspace.openTextDocument(uri); const editor = await vscode.window.showTextDocument(doc); @@ -512,8 +503,8 @@ export async function activate(context: vscode.ExtensionContext) { ); editor.selection = new vscode.Selection(pos, pos); editor.revealRange(new vscode.Range(pos, pos)); - } catch (e) { - vscode.window.showErrorMessage(`Could not open finding: ${e}`); + } catch { + vscode.window.showErrorMessage("Could not open finding."); } }, ), diff --git a/extensions/vscode/src/services/ackitWorkspace.ts b/extensions/vscode/src/services/ackitWorkspace.ts index 041350f1..05531d36 100644 --- a/extensions/vscode/src/services/ackitWorkspace.ts +++ b/extensions/vscode/src/services/ackitWorkspace.ts @@ -5,7 +5,6 @@ import { buildInstructionGraph, buildStatusReport, loadAckitConfig, - resolveEffectiveStack, scanRepository, scoreRepository, validateSkills, @@ -39,7 +38,9 @@ export class AckitWorkspaceService implements vscode.Disposable { private snapshots = new Map(); private disposables: vscode.Disposable[] = []; private debounceTimer: NodeJS.Timeout | undefined; - private currentAbort: AbortController | undefined; + private refreshes = new Map>(); + private controllers = new Map(); + private disposed = false; private readonly _onDidChange = new vscode.EventEmitter(); readonly onDidChange = this._onDidChange.event; @@ -65,8 +66,11 @@ export class AckitWorkspaceService implements vscode.Disposable { } dispose() { + if (this.disposed) return; + this.disposed = true; if (this.debounceTimer) clearTimeout(this.debounceTimer); - this.currentAbort?.abort(); + for (const controller of this.controllers.values()) controller.abort(); + this.controllers.clear(); this._onDidChange.dispose(); for (const d of this.disposables) d.dispose(); } @@ -94,6 +98,7 @@ export class AckitWorkspaceService implements vscode.Disposable { } async refreshAll(): Promise { + if (this.disposed) return; const roots = this.getRoots(); for (const root of roots) { await this.refreshRoot(root); @@ -101,30 +106,46 @@ export class AckitWorkspaceService implements vscode.Disposable { } private scheduleRefresh() { + if (this.disposed) return; if (this.debounceTimer) clearTimeout(this.debounceTimer); this.debounceTimer = setTimeout(() => { + this.debounceTimer = undefined; void this.refreshAll(); }, 400); } - async refreshRoot(root: string): Promise { - // Cancel previous - this.currentAbort?.abort(); + refreshRoot(root: string): Promise { + if (this.disposed) return Promise.resolve(); + // A watcher must not cancel an explicit caller and return stale data. + // Each root publishes complete snapshots in request order. + const previous = this.refreshes.get(root) ?? Promise.resolve(); + const current = previous.then(() => this.performRefreshRoot(root)); + this.refreshes.set(root, current); + return current.finally(() => { + if (this.refreshes.get(root) === current) this.refreshes.delete(root); + }); + } + + private async performRefreshRoot(root: string): Promise { + if (this.disposed) return; const ac = new AbortController(); - this.currentAbort = ac; + this.controllers.set(root, ac); const signal = ac.signal; - const snapshot: WorkspaceSnapshot = this.snapshots.get(root) ?? { - root, - scan: null, - readiness: null, - graph: null, - diagnostics: null, - optimize: null, - taskStatus: null, - error: null, - updatedAt: 0, - }; + const oldSnapshot = this.snapshots.get(root); + const snapshot: WorkspaceSnapshot = oldSnapshot + ? { ...oldSnapshot } + : { + root, + scan: null, + readiness: null, + graph: null, + diagnostics: null, + optimize: null, + taskStatus: null, + error: null, + updatedAt: 0, + }; try { // Avoid scanning own cache/dist @@ -142,16 +163,16 @@ export class AckitWorkspaceService implements vscode.Disposable { // Use scoreRepository with minimal inputs const readiness = scoreRepository( { - graph: graph as never, - pack: pack as never, + graph, + pack, scan, - skills: skills as never, - policy: { findings: [] } as never, - tasks: { dirExists: true, totalTasks: 0 } as never, + skills, + policy: { findings: [] }, + tasks: { dirExists: true, totalTasks: 0 }, }, {}, ); - snapshot.readiness = readiness as unknown as ScoreReport; + snapshot.readiness = readiness; } catch { snapshot.readiness = null; } @@ -203,9 +224,12 @@ export class AckitWorkspaceService implements vscode.Disposable { if ((e as DOMException).name === "AbortError") return; snapshot.error = (e as Error).message; } finally { - snapshot.updatedAt = Date.now(); - this.snapshots.set(root, snapshot); - this._onDidChange.fire(root); + if (this.controllers.get(root) === ac) this.controllers.delete(root); + if (!this.disposed && !signal.aborted) { + snapshot.updatedAt = Date.now(); + this.snapshots.set(root, snapshot); + this._onDidChange.fire(root); + } } } } diff --git a/extensions/vscode/src/test/runTest.ts b/extensions/vscode/src/test/runTest.ts index cdd96195..af365480 100644 --- a/extensions/vscode/src/test/runTest.ts +++ b/extensions/vscode/src/test/runTest.ts @@ -1,26 +1,37 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; import * as path from "node:path"; import { runTests } from "@vscode/test-electron"; async function main() { + const workspacePath = mkdtempSync(path.join(tmpdir(), "ackit-vscode-test-")); + if ( + path.dirname(workspacePath) !== path.resolve(tmpdir()) || + !path.basename(workspacePath).startsWith("ackit-vscode-test-") + ) + throw new Error("Unsafe test workspace"); try { const extensionDevelopmentPath = path.resolve(__dirname, "../../"); const extensionTestsPath = path.resolve(__dirname, "./suite/index"); - const workspacePath = path.resolve(__dirname, "../../test-fixture"); - // Create a disposable workspace with a simple fixture - const { mkdirSync, writeFileSync, existsSync } = await import("node:fs"); - if (!existsSync(workspacePath)) { - mkdirSync(workspacePath, { recursive: true }); - writeFileSync(path.join(workspacePath, "AGENTS.md"), "# AGENTS\nUse ackit task\n", "utf8"); - writeFileSync(path.join(workspacePath, "README.md"), "# Fixture\n", "utf8"); - } + writeFileSync(path.join(workspacePath, "AGENTS.md"), "# AGENTS\nUse ackit task\n", "utf8"); + writeFileSync(path.join(workspacePath, "README.md"), "# Fixture\n", "utf8"); + writeFileSync(path.join(workspacePath, "sample.txt"), "TODO: review fixture\n", "utf8"); await runTests({ extensionDevelopmentPath, extensionTestsPath, - launchArgs: [workspacePath, "--disable-extensions"], + launchArgs: [ + workspacePath, + "--disable-extensions", + "--disable-workspace-trust", + "--skip-welcome", + "--skip-release-notes", + ], }); } catch (err) { console.error("Failed to run tests", err); - process.exit(1); + process.exitCode = 1; + } finally { + rmSync(workspacePath, { recursive: true, force: true }); } } diff --git a/extensions/vscode/src/test/suite/extension.test.ts b/extensions/vscode/src/test/suite/extension.test.ts index f255f375..2fc0a207 100644 --- a/extensions/vscode/src/test/suite/extension.test.ts +++ b/extensions/vscode/src/test/suite/extension.test.ts @@ -1,120 +1,118 @@ import * as assert from "node:assert"; -import * as vscode from "vscode"; -import * as path from "node:path"; import * as fs from "node:fs"; +import * as path from "node:path"; +import * as vscode from "vscode"; +import type { WorkspaceSnapshot } from "../../services/ackitWorkspace.js"; suite("ACKit Extension Integration", () => { - test("extension activates", async () => { + let root: string; + let snapshot: WorkspaceSnapshot; + suiteSetup(async () => { + const folder = vscode.workspace.workspaceFolders?.[0]; + assert.ok(folder, "Disposable workspace missing"); + root = folder.uri.fsPath; const ext = vscode.extensions.getExtension("Cynrath.ackit-vscode"); assert.ok(ext, "Extension not found"); - if (!ext.isActive) await ext.activate(); + await ext.activate(); assert.ok(ext.isActive, "Extension not active"); + snapshot = await vscode.commands.executeCommand("ackit.refresh"); }); - test("ACKit activity container exists", async () => { - // The activity bar container is registered via package.json; check that views are registered - // We can't directly query activity bar, but we can check that tree views can be created + test("registers every advertised command and view", async () => { const ext = vscode.extensions.getExtension("Cynrath.ackit-vscode"); - assert.ok(ext); - // Check contributes.views - const pkg = ext.packageJSON as { contributes?: { views?: Record> } }; - const views = pkg.contributes?.views?.ackit?.map((v) => v.id) ?? []; - assert.ok(views.includes("ackit.readiness"), "ackit.readiness view missing"); - assert.ok(views.includes("ackit.findings"), "ackit.findings view missing"); - assert.ok(views.includes("ackit.graph"), "ackit.graph view missing"); - }); - - test("Readiness tree has real data", async () => { - // Trigger refresh and check that readiness provider returns data - await vscode.commands.executeCommand("ackit.refresh"); - // Wait a bit for async refresh - await new Promise((r) => setTimeout(r, 1500)); - // The tree view should have items; we can't easily query tree data, but we can check that diagnostics are not empty? - // As a proxy, check that the extension's service has updated - // For now, just assert that refresh command succeeded without throwing - assert.ok(true); - }); - - test("Findings tree has real data", async () => { - await vscode.commands.executeCommand("ackit.refresh"); - await new Promise((r) => setTimeout(r, 1000)); - assert.ok(true); - }); - - test("Problems diagnostics appear", async () => { - // After refresh, diagnostics collection should have entries - await vscode.commands.executeCommand("ackit.refresh"); - await new Promise((r) => setTimeout(r, 1200)); - const diags = vscode.languages.getDiagnostics(); - // At least one diagnostic may exist from fixture, or none if clean โ€” just ensure no crash - assert.ok(Array.isArray(diags)); + assert.ok(ext?.isActive); + const pkg = ext.packageJSON as { + contributes: { commands: { command: string }[]; views: { ackit: { id: string }[] } }; + }; + const commands = await vscode.commands.getCommands(true); + for (const command of pkg.contributes.commands) + assert.ok(commands.includes(command.command), command.command); + for (const view of ["ackit.readiness", "ackit.findings", "ackit.graph", "ackit.tasks"]) + assert.ok( + pkg.contributes.views.ackit.some((item) => item.id === view), + view, + ); }); - - test("Instructions-for-current-file works", async () => { - // Create a test file and try to resolve instructions - const ws = vscode.workspace.workspaceFolders?.[0]; - if (!ws) return; - const testFile = path.join(ws.uri.fsPath, "src", "test-current.ts"); - fs.mkdirSync(path.dirname(testFile), { recursive: true }); - fs.writeFileSync(testFile, "console.log('test');", "utf8"); - const uri = vscode.Uri.file(testFile); - const doc = await vscode.workspace.openTextDocument(uri); - await vscode.window.showTextDocument(doc); - // Execute the command; it should not throw - try { - await vscode.commands.executeCommand("ackit.instructionsForCurrentFile"); - } catch { - // The command may be named differently; try again without Thenable.catch - try { - await vscode.commands.executeCommand("ackit.instructionsForCurrentFile"); - } catch { - // ignore - } - } - // Cleanup - fs.unlinkSync(testFile); - assert.ok(true); + test("service provides real scan, graph, readiness and optimization data", () => { + assert.ok(snapshot); + assert.strictEqual(snapshot.error, null); + assert.ok( + snapshot.scan?.findings.some( + (finding) => finding.relativePath === "sample.txt" && finding.ruleId === "ACKIT020", + ), + ); + assert.ok(snapshot.graph?.nodes.some((node) => node.relativePath === "AGENTS.md")); + assert.ok(snapshot.readiness, "SDK identity/templates failed to load"); + assert.ok(Number.isFinite(snapshot.readiness.overall)); + assert.ok(Array.isArray(snapshot.optimize)); }); - - test("graph command works", async () => { - await vscode.commands.executeCommand("ackit.showGraph"); - assert.ok(true); + test("refresh publishes actual ACKit diagnostics for the fixture finding", async () => { + const snapshot = await vscode.commands.executeCommand("ackit.refresh"); + assert.ok(snapshot?.readiness, "Packaged SDK identity/templates failed to load"); + assert.ok(Number.isFinite(snapshot.readiness.overall)); + const uri = vscode.Uri.file(path.join(root, "sample.txt")); + const diagnostics = vscode.languages + .getDiagnostics(uri) + .filter((item) => item.source === "ackit"); + assert.ok( + diagnostics.some((item) => item.code === "ACKIT020"), + "Fixture diagnostic missing", + ); }); - - test("optimize produces real findings", async () => { - // Execute optimize command; it should show quick pick or message, not just terminal - try { - await vscode.commands.executeCommand("ackit.optimize"); - } catch {} - assert.ok(true); + test("opens a contained finding and refuses traversal", async () => { + await vscode.commands.executeCommand("ackit.openFinding", { + relativePath: "sample.txt", + line: 1, + column: 1, + }); + const editor = vscode.window.activeTextEditor; + assert.strictEqual(editor?.document.uri.fsPath, path.join(root, "sample.txt")); + await vscode.commands.executeCommand("ackit.openFinding", { + relativePath: "../outside.txt", + line: 1, + column: 1, + }); + assert.strictEqual( + vscode.window.activeTextEditor?.document.uri.fsPath, + editor?.document.uri.fsPath, + ); }); - - test("diagnostics command uses real diagnostics", async () => { + test("diagnostics command opens actual JSON output", async () => { await vscode.commands.executeCommand("ackit.diagnostics"); - // Should open a document with JSON - await new Promise((r) => setTimeout(r, 800)); - const editor = vscode.window.activeTextEditor; - // If diagnostics opened a JSON doc, it will be active - assert.ok(editor || true); + const document = vscode.window.activeTextEditor?.document; + assert.strictEqual(document?.languageId, "json"); + const data = JSON.parse(document?.getText() ?? "null") as { config: unknown; tasks: unknown }; + assert.strictEqual(data.config, "ok"); + assert.strictEqual(data.tasks, "ok"); }); - - test("refresh works after file create/change/delete", async () => { - const ws = vscode.workspace.workspaceFolders?.[0]; - if (!ws) return; - const tmpFile = path.join(ws.uri.fsPath, `tmp-${Date.now()}.md`); - fs.writeFileSync(tmpFile, "# Test\n", "utf8"); - await vscode.commands.executeCommand("ackit.refresh"); - await new Promise((r) => setTimeout(r, 800)); - fs.writeFileSync(tmpFile, "# Test changed\n", "utf8"); - await new Promise((r) => setTimeout(r, 800)); - fs.unlinkSync(tmpFile); - await new Promise((r) => setTimeout(r, 800)); - await vscode.commands.executeCommand("ackit.refresh"); - assert.ok(true); + test("service reflects a fixture create/change/delete lifecycle", async () => { + const file = path.join(root, "lifecycle.txt"); + fs.writeFileSync(file, "TODO: lifecycle fixture\n", "utf8"); + snapshot = await vscode.commands.executeCommand("ackit.refresh"); + assert.ok(snapshot.scan?.findings.some((finding) => finding.relativePath === "lifecycle.txt")); + fs.writeFileSync(file, "Resolved lifecycle fixture\n", "utf8"); + snapshot = await vscode.commands.executeCommand("ackit.refresh"); + assert.ok(!snapshot.scan?.findings.some((finding) => finding.relativePath === "lifecycle.txt")); + fs.unlinkSync(file); + snapshot = await vscode.commands.executeCommand("ackit.refresh"); + assert.strictEqual(snapshot.error, null); }); - - test("extension host does not crash", async () => { - const ext = vscode.extensions.getExtension("Cynrath.ackit-vscode"); - assert.ok(ext?.isActive); + test("overlapping explicit refreshes each return a completed current scan", async () => { + const file = path.join(root, "overlap.txt"); + fs.writeFileSync(file, "TODO: overlapping refresh fixture\n", "utf8"); + try { + const inspect = () => + vscode.commands + .executeCommand("ackit.refresh") + .then((value) => + Boolean( + value?.scan?.findings.some((finding) => finding.relativePath === "overlap.txt"), + ), + ); + assert.deepStrictEqual(await Promise.all([inspect(), inspect()]), [true, true]); + } finally { + fs.unlinkSync(file); + await vscode.commands.executeCommand("ackit.refresh"); + } }); }); diff --git a/extensions/vscode/src/test/suite/index.ts b/extensions/vscode/src/test/suite/index.ts index 119ca048..ff2cd579 100644 --- a/extensions/vscode/src/test/suite/index.ts +++ b/extensions/vscode/src/test/suite/index.ts @@ -1,11 +1,12 @@ import * as path from "node:path"; -import Mocha from "mocha"; import { glob } from "glob"; +import Mocha from "mocha"; export async function run(): Promise { const mocha = new Mocha({ ui: "tdd", color: true, timeout: 20000 }); const testsRoot = path.resolve(__dirname, "."); - const files = await glob("**/*.test.js", { cwd: testsRoot }); + const files = await glob("**/extension.test.js", { cwd: testsRoot }); + if (files.length === 0) throw new Error("No Electron integration tests found"); for (const file of files) { mocha.addFile(path.resolve(testsRoot, file)); } diff --git a/extensions/vscode/src/test/suite/unit.test.ts b/extensions/vscode/src/test/suite/unit.test.ts index 2a3de0ea..f799f256 100644 --- a/extensions/vscode/src/test/suite/unit.test.ts +++ b/extensions/vscode/src/test/suite/unit.test.ts @@ -1,57 +1,59 @@ import * as assert from "node:assert"; -import * as vscode from "vscode"; +import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { diagnosticKind, resolveFindingPath } from "../../diagnostics.js"; -suite("ACKit Unit Tests", () => { - test("severity mapping", () => { - // Verify that findings severity maps to DiagnosticSeverity correctly - // This is a pure logic test, no VS Code API needed beyond enum - const map = (sev: string) => { - if (sev === "critical" || sev === "high") return vscode.DiagnosticSeverity.Error; - if (sev === "medium") return vscode.DiagnosticSeverity.Warning; - if (sev === "low") return vscode.DiagnosticSeverity.Information; - return vscode.DiagnosticSeverity.Hint; - }; - assert.strictEqual(map("critical"), vscode.DiagnosticSeverity.Error); - assert.strictEqual(map("high"), vscode.DiagnosticSeverity.Error); - assert.strictEqual(map("medium"), vscode.DiagnosticSeverity.Warning); - assert.strictEqual(map("low"), vscode.DiagnosticSeverity.Information); - assert.strictEqual(map("info"), vscode.DiagnosticSeverity.Hint); +suite("ACKit diagnostic boundaries (without a VS Code host)", () => { + for (const [severity, expected] of Object.entries({ + critical: "Error", + high: "Error", + medium: "Warning", + low: "Information", + info: "Hint", + })) { + test(`maps ${severity} to ${expected}`, () => + assert.strictEqual(diagnosticKind(severity), expected)); + } + let fixture: string; + let root: string; + setup(() => { + fixture = mkdtempSync(path.join(tmpdir(), "ackit-vscode-unit-")); + root = path.join(fixture, "repo"); + mkdirSync(path.join(root, "src"), { recursive: true }); + mkdirSync(path.join(fixture, "repo-other")); + writeFileSync(path.join(root, "src", "app.ts"), "fixture\n"); + writeFileSync(path.join(fixture, "repo-other", "outside.txt"), "outside\n"); }); - - test("path handling โ€” safe Uri.joinPath", () => { - const root = "/tmp/workspace"; - const rel = "src/app.ts"; - const uri = vscode.Uri.joinPath(vscode.Uri.file(root), rel); - assert.ok(uri.fsPath.endsWith("src/app.ts") || uri.fsPath.includes("src")); - // Ensure that absolute path outside root is not joined blindly - const evil = "/etc/passwd"; - // Our code should check isInsideRoot before joining - assert.ok(!evil.startsWith(root)); + teardown(() => { + assert.strictEqual(path.dirname(fixture), path.resolve(tmpdir())); + assert.ok(path.basename(fixture).startsWith("ackit-vscode-unit-")); + rmSync(fixture, { recursive: true, force: true }); }); - - test("multi-root selection", () => { - // Simulate multi-root logic: active editor's folder should be preferred - // This is a logic test, not requiring actual workspace - const roots = ["/a", "/b", "/c"]; - const active = "/b/src/file.ts"; - const folder = roots.find((r) => active.startsWith(r)); - assert.strictEqual(folder, "/b"); + test("resolves a real contained file with portable separators", () => { + const expected = realpathSync(path.join(root, "src", "app.ts")); + assert.strictEqual(resolveFindingPath(root, "src/app.ts"), expected); + assert.strictEqual(resolveFindingPath(root, "src\\app.ts"), expected); }); - - test("watch debounce", async () => { - let count = 0; - let timer: NodeJS.Timeout | undefined; - const schedule = () => { - if (timer) clearTimeout(timer); - timer = setTimeout(() => count++, 100); - }; - schedule(); schedule(); schedule(); - await new Promise((r) => setTimeout(r, 250)); - assert.strictEqual(count, 1); + test("rejects traversal, sibling-prefix, absolute, empty and NUL paths", () => { + for (const relative of [ + "../repo-other/outside.txt", + "..\\repo-other\\outside.txt", + path.join(root, "src/app.ts"), + "C:\\outside.txt", + "", + "src\0app.ts", + "missing.ts", + ]) { + assert.strictEqual(resolveFindingPath(root, relative), null, relative); + } }); - - test("error states", () => { - const snap = { error: "test error", scan: null } as unknown as { error: string | null; scan: unknown }; - assert.ok(snap.error); + test("rejects a directory junction/symlink escaping the workspace", () => { + symlinkSync( + path.join(fixture, "repo-other"), + path.join(root, "link"), + process.platform === "win32" ? "junction" : "dir", + ); + assert.strictEqual(resolveFindingPath(root, "link/outside.txt"), null); }); }); diff --git a/package.json b/package.json index 6c146835..1037fc12 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@cynrath/agent-context-kit", - "version": "0.5.4", + "version": "0.5.5", "description": "Agent context and repository readiness toolkit for Codex, Claude Code, Cursor, Copilot, Gemini and MCP-based coding agents. Validates agent instructions, scans repositories, optimizes context and enforces evidence-backed workflows. Offline-first and deterministic.", "keywords": [ "ackit", @@ -79,15 +79,16 @@ "test": "vitest run", "check:text-hygiene": "node scripts/check-text-hygiene.mjs --repo", "smoke:cli": "node tests/e2e/cli-scaffold.smoke.mjs", + "smoke:action": "node scripts/action-consumer-smoke.mjs", "smoke:package": "node scripts/package-smoke.mjs" }, "dependencies": { - "@modelcontextprotocol/sdk": "^1.30.0", + "@modelcontextprotocol/sdk": "^1.32.2", "commander": "^15.0.0", "ignore": "^7.0.6", "picomatch": "^4.0.5", "yaml": "^2.9.0", - "zod": "^4.4.3" + "zod": "^4.6.7" }, "devDependencies": { "@biomejs/biome": "^2.5.10", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b7843836..308a0a72 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -9,8 +9,8 @@ importers: .: dependencies: '@modelcontextprotocol/sdk': - specifier: ^1.30.0 - version: 1.30.0(supports-color@7.2.0)(zod@4.4.3) + specifier: ^1.32.2 + version: 1.32.2(supports-color@8.1.1)(zod@4.6.7) commander: specifier: ^15.0.0 version: 15.0.0 @@ -24,8 +24,8 @@ importers: specifier: ^2.9.0 version: 2.9.0 zod: - specifier: ^4.4.3 - version: 4.4.3 + specifier: ^4.6.7 + version: 4.6.7 devDependencies: '@biomejs/biome': specifier: ^2.5.10 @@ -301,11 +301,11 @@ packages: cpu: [x64] os: [win32] - '@hono/node-server@2.1.1': - resolution: {integrity: sha512-ELuehkj5VCBdgEw9zs+ivkKwyzzUCSQuE96YmiPvn1ECBoZCczbFXJLeEGMTYjphP6gydh4pHMqEYPVMYUVgQg==} + '@hono/node-server@2.1.8': + resolution: {integrity: sha512-jdf7FHh6A1lzjpHHQUgxsg2GeER2vMetnAOfeActzcoli6jamlK+NAwL6Dsr5Fl3BS3tYUQzCdtZjU8Qxv7bEA==} engines: {node: '>=20'} peerDependencies: - hono: ^4 + hono: ^4 || ^5.0.0-0 '@isaacs/cliui@8.0.2': resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==} @@ -321,8 +321,8 @@ packages: '@jridgewell/trace-mapping@0.3.31': resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==} - '@modelcontextprotocol/sdk@1.30.0': - resolution: {integrity: sha512-xKd8OIzlqNzcqcNumGAa6g+PW2kjD5vrpcKOnfldAUPP3j7lnqMPwlTXQm8gF+UwH72z0lqaRbjr9hqGz0eITA==} + '@modelcontextprotocol/sdk@1.32.2': + resolution: {integrity: sha512-SWsVtH/0vULSQStoZ6xxH2K09Li8fXYTMC64ZeogCdpZ3XSi1eCPOByV1OpuJxuI3OcmHhosDWYyii07tpPsLw==} engines: {node: '>=18'} peerDependencies: '@cfworker/json-schema': ^4.1.1 @@ -686,8 +686,8 @@ packages: resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==} engines: {node: '>=8'} - body-parser@2.3.0: - resolution: {integrity: sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==} + body-parser@2.4.0: + resolution: {integrity: sha512-Ifk1KcLrxaGt1occQagQNFNNOqRt1LFuehEnHHzB8Z6cRgIxRU1TBaiIsUiCdA+gy5PL7Y1IX31DNKkRmxtXjQ==} engines: {node: '>=18'} brace-expansion@2.1.4: @@ -754,8 +754,8 @@ packages: resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==} engines: {node: '>=22.12.0'} - content-disposition@1.1.0: - resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==} + content-disposition@2.0.1: + resolution: {integrity: sha512-e+H0ZXHSWYrENhQzw1LPuP4oF5MzVKmDU6d3hxlvaPEYLLg62MxtQNPRx4SYSuYJSBUgnQIG4HIN2tEtNv7Dog==} engines: {node: '>=18'} content-type@1.0.5: @@ -832,8 +832,8 @@ packages: emoji-regex@9.2.2: resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==} - encodeurl@2.0.0: - resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==} + encodeurl@2.0.3: + resolution: {integrity: sha512-mIteYONiEfc4xWf2F1WXovh1c8npzS00vNeiUPdwFF+QlVJni+gNvpQltLMQhob8rew/bWWc/bGTuUr0EUGt0w==} engines: {node: '>= 0.8'} es-define-property@1.0.1: @@ -886,21 +886,21 @@ packages: resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==} engines: {node: '>=12.0.0'} - express-rate-limit@8.6.2: - resolution: {integrity: sha512-YH4ru+eOJxQABscKFfRCy9R7x9QFGdezclVMwwgFFndzS2Xnm0uo6B0ABZsLhcpeptGv2qvuJVWlQr9gQZoC3A==} + express-rate-limit@8.7.4: + resolution: {integrity: sha512-LKBXzX700wz3zAGNNmVnjRI5mEbYkLv7UbMI4+9Xa+JPcg2UZh6AgY/2CZh9RrJjFM5ttC/N1lD+KzyFoZITCw==} engines: {node: '>= 16'} peerDependencies: express: '>= 4.11' - express@5.2.1: - resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==} + express@5.3.0: + resolution: {integrity: sha512-qCqy1xSoaugxOD4IVHb1ZWdkvCF2W3aE2okKouWj8VwJ+ztskSiXoBnCSJqfKT+cVPJhuJqe9YLbY425+Zh00g==} engines: {node: '>= 18'} fast-deep-equal@3.1.3: resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==} - fast-uri@3.1.5: - resolution: {integrity: sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==} + fast-uri@3.1.9: + resolution: {integrity: sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==} fdir@6.5.0: resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} @@ -1000,8 +1000,8 @@ packages: resolution: {integrity: sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==} hasBin: true - hono@4.13.3: - resolution: {integrity: sha512-r8AO2mYHoLxSHkgafNeC/BXyb2vWRxD3jem4Ts+ptav8oTG5FIRifAjuJEmZI4bSvvc2ns0GxmIYiZnHqN3mMw==} + hono@4.13.18: + resolution: {integrity: sha512-H9q/E1XizaWstJxUW881dmLxEj+t/TrGGnyxINkm4+sK0qUwsMtFdo2BWI9Vs3cIS19MU6b6iCijoUoEf4f3DA==} engines: {node: '>=16.9.0'} html-escaper@2.0.2: @@ -1037,8 +1037,8 @@ packages: inherits@2.0.4: resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==} - ip-address@10.5.0: - resolution: {integrity: sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==} + ip-address@10.7.6: + resolution: {integrity: sha512-00LYkM6byILa9eQIx6qoaXCM40xTLd56AZ4vyaPW3YTyb49VZYPo5xsiAq4tuQ54GH4R7gVdYScJ1B7B77PuTg==} engines: {node: '>= 12'} ipaddr.js@1.9.1: @@ -1109,8 +1109,8 @@ packages: jackspeak@3.4.3: resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==} - jose@6.2.10: - resolution: {integrity: sha512-iiW7J9qRFlGxvCOIBDBDxFePQSn7ZMAnrYGhrrOo6siO/MIqwfyilLR27pkfDgUk+raLuzADS8A3S/KLBisc0g==} + jose@6.2.17: + resolution: {integrity: sha512-wOuK9V1yujQFH5S0ZWmLcDZN7+IKh9bUCC2ZPCf2HDlol3WWHy+PPyNjEI75FXRLMp3vDKQcupP59xhVU95hcg==} js-tokens@10.0.0: resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==} @@ -1299,8 +1299,8 @@ packages: resolution: {integrity: sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==} engines: {node: '>=12.20.0'} - on-finished@2.4.1: - resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==} + on-finished@2.4.2: + resolution: {integrity: sha512-ATWUv387i+nLD49EiDoOft5scf32Vsdz3ktrQJG9bi7jRFmaXTssvyvj1EmeKVVgvesbqUtvQQvaS2TpTukAZQ==} engines: {node: '>= 0.8'} once@1.4.0: @@ -1372,12 +1372,12 @@ packages: process-nextick-args@2.0.1: resolution: {integrity: sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==} - proxy-addr@2.0.7: - resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==} + proxy-addr@2.0.8: + resolution: {integrity: sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==} engines: {node: '>= 0.10'} - qs@6.15.3: - resolution: {integrity: sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==} + qs@6.17.1: + resolution: {integrity: sha512-jd3COkaKVgGUW+ZHyEHCG9bH7RoaaiWuMgzsIBjUMVjLAaWGWpoUAVwljVvBHxRu/2qEHnadLGZrkutYUBPQJA==} engines: {node: '>=0.6'} randombytes@2.1.0: @@ -1726,8 +1726,8 @@ packages: peerDependencies: zod: ^3.25.28 || ^4 - zod@4.4.3: - resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==} + zod@4.6.7: + resolution: {integrity: sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==} snapshots: @@ -1853,9 +1853,9 @@ snapshots: '@esbuild/win32-x64@0.23.1': optional: true - '@hono/node-server@2.1.1(hono@4.13.3)': + '@hono/node-server@2.1.8(hono@4.13.18)': dependencies: - hono: 4.13.3 + hono: 4.13.18 '@isaacs/cliui@8.0.2': dependencies: @@ -1875,9 +1875,9 @@ snapshots: '@jridgewell/resolve-uri': 3.1.2 '@jridgewell/sourcemap-codec': 1.5.5 - '@modelcontextprotocol/sdk@1.30.0(supports-color@7.2.0)(zod@4.4.3)': + '@modelcontextprotocol/sdk@1.32.2(supports-color@8.1.1)(zod@4.6.7)': dependencies: - '@hono/node-server': 2.1.1(hono@4.13.3) + '@hono/node-server': 2.1.8(hono@4.13.18) ajv: 8.20.0 ajv-formats: 3.0.1(ajv@8.20.0) content-type: 1.0.5 @@ -1885,15 +1885,15 @@ snapshots: cross-spawn: 7.0.6 eventsource: 3.0.7 eventsource-parser: 3.1.1 - express: 5.2.1(supports-color@8.1.1) - express-rate-limit: 8.6.2(express@5.2.1(supports-color@8.1.1))(supports-color@7.2.0) - hono: 4.13.3 - jose: 6.2.10 + express: 5.3.0(supports-color@8.1.1) + express-rate-limit: 8.7.4(express@5.3.0(supports-color@8.1.1))(supports-color@8.1.1) + hono: 4.13.18 + jose: 6.2.17 json-schema-typed: 8.0.2 pkce-challenge: 5.0.1 raw-body: 3.0.2 - zod: 4.4.3 - zod-to-json-schema: 3.25.2(zod@4.4.3) + zod: 4.6.7 + zod-to-json-schema: 3.25.2(zod@4.6.7) transitivePeerDependencies: - supports-color @@ -2113,7 +2113,7 @@ snapshots: ajv@8.20.0: dependencies: fast-deep-equal: 3.1.3 - fast-uri: 3.1.5 + fast-uri: 3.1.9 json-schema-traverse: 1.0.0 require-from-string: 2.0.2 @@ -2148,15 +2148,15 @@ snapshots: binary-extensions@2.3.0: {} - body-parser@2.3.0(supports-color@7.2.0): + body-parser@2.4.0(supports-color@8.1.1): dependencies: bytes: 3.1.2 content-type: 2.1.0 - debug: 4.4.3(supports-color@7.2.0) + debug: 4.4.3(supports-color@8.1.1) http-errors: 2.0.1 iconv-lite: 0.7.3 - on-finished: 2.4.1 - qs: 6.15.3 + on-finished: 2.4.2 + qs: 6.17.1 raw-body: 3.0.2 type-is: 2.1.0 transitivePeerDependencies: @@ -2227,7 +2227,7 @@ snapshots: commander@15.0.0: {} - content-disposition@1.1.0: {} + content-disposition@2.0.1: {} content-type@1.0.5: {} @@ -2252,12 +2252,6 @@ snapshots: shebang-command: 2.0.0 which: 2.0.2 - debug@4.4.3(supports-color@7.2.0): - dependencies: - ms: 2.1.3 - optionalDependencies: - supports-color: 7.2.0 - debug@4.4.3(supports-color@8.1.1): dependencies: ms: 2.1.3 @@ -2288,7 +2282,7 @@ snapshots: emoji-regex@9.2.2: {} - encodeurl@2.0.0: {} + encodeurl@2.0.3: {} es-define-property@1.0.1: {} @@ -2347,40 +2341,40 @@ snapshots: expect-type@1.4.0: {} - express-rate-limit@8.6.2(express@5.2.1(supports-color@8.1.1))(supports-color@7.2.0): + express-rate-limit@8.7.4(express@5.3.0(supports-color@8.1.1))(supports-color@8.1.1): dependencies: - debug: 4.4.3(supports-color@7.2.0) - express: 5.2.1(supports-color@8.1.1) - ip-address: 10.5.0 + debug: 4.4.3(supports-color@8.1.1) + express: 5.3.0(supports-color@8.1.1) + ip-address: 10.7.6 transitivePeerDependencies: - supports-color - express@5.2.1(supports-color@8.1.1): + express@5.3.0(supports-color@8.1.1): dependencies: accepts: 2.0.0 - body-parser: 2.3.0(supports-color@7.2.0) - content-disposition: 1.1.0 - content-type: 1.0.5 + body-parser: 2.4.0(supports-color@8.1.1) + content-disposition: 2.0.1 + content-type: 2.1.0 cookie: 0.7.2 cookie-signature: 1.2.2 - debug: 4.4.3(supports-color@7.2.0) + debug: 4.4.3(supports-color@8.1.1) depd: 2.0.0 - encodeurl: 2.0.0 + encodeurl: 2.0.3 escape-html: 1.0.3 etag: 1.8.1 - finalhandler: 2.1.1(supports-color@7.2.0) + finalhandler: 2.1.1(supports-color@8.1.1) fresh: 2.0.0 http-errors: 2.0.1 merge-descriptors: 2.0.0 mime-types: 3.0.2 - on-finished: 2.4.1 + on-finished: 2.4.2 once: 1.4.0 parseurl: 1.3.3 - proxy-addr: 2.0.7 - qs: 6.15.3 + proxy-addr: 2.0.8 + qs: 6.17.1 range-parser: 1.3.0 - router: 2.2.0(supports-color@7.2.0) - send: 1.2.1(supports-color@7.2.0) + router: 2.2.0(supports-color@8.1.1) + send: 1.2.1(supports-color@8.1.1) serve-static: 2.2.1(supports-color@8.1.1) statuses: 2.0.2 type-is: 2.1.0 @@ -2390,7 +2384,7 @@ snapshots: fast-deep-equal@3.1.3: {} - fast-uri@3.1.5: {} + fast-uri@3.1.9: {} fdir@6.5.0(picomatch@4.0.5): optionalDependencies: @@ -2400,12 +2394,12 @@ snapshots: dependencies: to-regex-range: 5.0.1 - finalhandler@2.1.1(supports-color@7.2.0): + finalhandler@2.1.1(supports-color@8.1.1): dependencies: - debug: 4.4.3(supports-color@7.2.0) - encodeurl: 2.0.0 + debug: 4.4.3(supports-color@8.1.1) + encodeurl: 2.0.3 escape-html: 1.0.3 - on-finished: 2.4.1 + on-finished: 2.4.2 parseurl: 1.3.3 statuses: 2.0.2 transitivePeerDependencies: @@ -2489,7 +2483,7 @@ snapshots: he@1.2.0: {} - hono@4.13.3: {} + hono@4.13.18: {} html-escaper@2.0.2: {} @@ -2530,7 +2524,7 @@ snapshots: inherits@2.0.4: {} - ip-address@10.5.0: {} + ip-address@10.7.6: {} ipaddr.js@1.9.1: {} @@ -2583,7 +2577,7 @@ snapshots: optionalDependencies: '@pkgjs/parseargs': 0.11.0 - jose@6.2.10: {} + jose@6.2.17: {} js-tokens@10.0.0: {} @@ -2748,7 +2742,7 @@ snapshots: obug@2.1.4: {} - on-finished@2.4.1: + on-finished@2.4.2: dependencies: ee-first: 1.1.1 @@ -2815,12 +2809,12 @@ snapshots: process-nextick-args@2.0.1: {} - proxy-addr@2.0.7: + proxy-addr@2.0.8: dependencies: forwarded: 0.2.0 ipaddr.js: 1.9.1 - qs@6.15.3: + qs@6.17.1: dependencies: es-define-property: 1.0.1 side-channel: 1.1.1 @@ -2882,9 +2876,9 @@ snapshots: '@rolldown/binding-win32-arm64-msvc': 1.2.5 '@rolldown/binding-win32-x64-msvc': 1.2.5 - router@2.2.0(supports-color@7.2.0): + router@2.2.0(supports-color@8.1.1): dependencies: - debug: 4.4.3(supports-color@7.2.0) + debug: 4.4.3(supports-color@8.1.1) depd: 2.0.0 is-promise: 4.0.0 parseurl: 1.3.3 @@ -2900,33 +2894,17 @@ snapshots: semver@7.8.5: {} - send@1.2.1(supports-color@7.2.0): - dependencies: - debug: 4.4.3(supports-color@7.2.0) - encodeurl: 2.0.0 - escape-html: 1.0.3 - etag: 1.8.1 - fresh: 2.0.0 - http-errors: 2.0.1 - mime-types: 3.0.2 - ms: 2.1.3 - on-finished: 2.4.1 - range-parser: 1.3.0 - statuses: 2.0.2 - transitivePeerDependencies: - - supports-color - send@1.2.1(supports-color@8.1.1): dependencies: debug: 4.4.3(supports-color@8.1.1) - encodeurl: 2.0.0 + encodeurl: 2.0.3 escape-html: 1.0.3 etag: 1.8.1 fresh: 2.0.0 http-errors: 2.0.1 mime-types: 3.0.2 ms: 2.1.3 - on-finished: 2.4.1 + on-finished: 2.4.2 range-parser: 1.3.0 statuses: 2.0.2 transitivePeerDependencies: @@ -2938,7 +2916,7 @@ snapshots: serve-static@2.2.1(supports-color@8.1.1): dependencies: - encodeurl: 2.0.0 + encodeurl: 2.0.3 escape-html: 1.0.3 parseurl: 1.3.3 send: 1.2.1(supports-color@8.1.1) @@ -3185,8 +3163,8 @@ snapshots: yocto-queue@0.1.0: {} - zod-to-json-schema@3.25.2(zod@4.4.3): + zod-to-json-schema@3.25.2(zod@4.6.7): dependencies: - zod: 4.4.3 + zod: 4.6.7 - zod@4.4.3: {} + zod@4.6.7: {} diff --git a/schemas/handoff.schema.json b/schemas/handoff.schema.json index 00307cfa..2c346e32 100644 --- a/schemas/handoff.schema.json +++ b/schemas/handoff.schema.json @@ -364,13 +364,9 @@ "type": "boolean" }, "problemCode": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "type": [ + "string", + "null" ] }, "changed": { @@ -395,13 +391,9 @@ ] }, "independenceCode": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "type": [ + "string", + "null" ] } }, diff --git a/schemas/instruction-graph.schema.json b/schemas/instruction-graph.schema.json index b5b91e6e..c88225d9 100644 --- a/schemas/instruction-graph.schema.json +++ b/schemas/instruction-graph.schema.json @@ -203,24 +203,16 @@ }, "shadowedBy": { "default": null, - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "type": [ + "string", + "null" ] }, "duplicateOf": { "default": null, - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "type": [ + "string", + "null" ] } }, diff --git a/schemas/task.schema.json b/schemas/task.schema.json index 1716f3f0..98c108d1 100644 --- a/schemas/task.schema.json +++ b/schemas/task.schema.json @@ -37,13 +37,9 @@ }, "completedAt": { "default": null, - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "type": [ + "string", + "null" ] }, "intentRef": { diff --git a/scripts/action-consumer-smoke.mjs b/scripts/action-consumer-smoke.mjs new file mode 100644 index 00000000..86f33dcc --- /dev/null +++ b/scripts/action-consumer-smoke.mjs @@ -0,0 +1,214 @@ +#!/usr/bin/env node +// An independent consumer must work from exported source, without ignored dist. +// Run through pnpm: pnpm run smoke:action [--ref vX.Y.Z] +import { spawnSync } from "node:child_process"; +import { + copyFileSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { runConsumerCommand } from "./consumer-command.mjs"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +const work = mkdtempSync(path.join(tmpdir(), "ackit-action-consumer-")); +// Validate the immutable recursive-cleanup target before any fixture work. +if ( + path.dirname(work) !== path.resolve(tmpdir()) || + !path.basename(work).startsWith("ackit-action-consumer-") +) { + throw new Error("Unsafe cleanup boundary"); +} +const source = path.join(work, "action"); +const consumer = path.join(work, "consumer"); +const pnpmCli = process.env.npm_execpath; +if (!pnpmCli || !existsSync(pnpmCli)) throw new Error("Run this smoke with pnpm run smoke:action"); +const paths = [ + "src", + "templates", + "schemas", + "package.json", + "pnpm-lock.yaml", + "pnpm-workspace.yaml", + "tsconfig.json", + "tsconfig.build.json", + "extensions/vscode/package.json", + "action.yml", + "scripts/action-package-path.mjs", +]; + +function run(command, args, options = {}) { + return runConsumerCommand(command, args, { cwd: root, ...options }, [ + [work, ""], + [root, ""], + ]); +} + +try { + mkdirSync(source); + mkdirSync(consumer); + const refIndex = process.argv.indexOf("--ref"); + if (refIndex !== -1) { + const ref = process.argv[refIndex + 1]; + if (!ref || !/^v\d+\.\d+\.\d+$/.test(ref)) throw new Error("Expected exact release tag"); + const archive = path.join(work, "action.tar"); + run("git", ["archive", "--format=tar", `--output=${archive}`, ref, ...paths]); + run("tar", ["-xf", archive, "-C", source]); + } else { + const files = run("git", [ + "ls-files", + "--cached", + "--others", + "--exclude-standard", + "-z", + "--", + ...paths, + ]) + .split("\0") + .filter(Boolean); + for (const file of files) { + const destination = path.resolve(source, file); + if (!destination.startsWith(`${source}${path.sep}`)) throw new Error("Invalid export path"); + mkdirSync(path.dirname(destination), { recursive: true }); + copyFileSync(path.join(root, file), destination); + } + } + if (existsSync(path.join(source, "dist")) || existsSync(path.join(source, "node_modules"))) + throw new Error("Export must start without runtime"); + const manifestOutput = run( + process.execPath, + [path.join(source, "scripts/action-package-path.mjs")], + { + cwd: consumer, + env: { ...process.env, GITHUB_WORKSPACE: consumer, ACKIT_ACTION_PATH: source }, + }, + ).trim(); + if (!manifestOutput.startsWith("path=")) throw new Error("Action manifest path output missing"); + const pinnedManifest = JSON.parse( + readFileSync(path.join(consumer, manifestOutput.slice(5)), "utf8"), + ); + if ( + pinnedManifest.packageManager !== + JSON.parse(readFileSync(path.join(source, "package.json"), "utf8")).packageManager + ) + throw new Error("Action manifest pin resolved to the consumer"); + run( + process.execPath, + [ + pnpmCli, + "install", + "--frozen-lockfile", + "--ignore-scripts", + "--filter", + "@cynrath/agent-context-kit", + ], + { cwd: source }, + ); + run(process.execPath, [pnpmCli, "build"], { cwd: source }); + run("git", ["init", "-q"], { cwd: consumer }); + writeFileSync(path.join(consumer, "AGENTS.md"), "# Consumer\nReview changes.\n"); + writeFileSync(path.join(consumer, "sample.txt"), "TODO: review fixture\n"); + const runAction = (threshold, args = "", expected = 0, command = "scan") => { + const outputs = mkdtempSync(path.join(work, "outputs-")); + const result = spawnSync(process.execPath, [path.join(source, "dist/action/index.js")], { + cwd: consumer, + encoding: "utf8", + timeout: 60_000, + windowsHide: true, + env: { + ...process.env, + INPUT_COMMAND: command, + INPUT_ARGS: args, + INPUT_FAIL_THRESHOLD: threshold, + INPUT_UPLOAD_SARIF: "true", + RUNNER_TEMP: outputs, + ACKIT_ROOT: consumer, + }, + }); + if (result.status !== expected) + throw new Error(`Action expected ${expected}, got ${result.status}: ${result.stderr}`); + return outputs; + }; + const outputs = runAction("high"); + const report = JSON.parse(readFileSync(path.join(outputs, "ackit-findings.json"), "utf8")); + if (!report.findings.some((finding) => finding.relativePath === "sample.txt")) + throw new Error("Action did not scan consumer"); + const sarif = JSON.parse(readFileSync(path.join(outputs, "ackit.sarif"), "utf8")); + const version = JSON.parse(readFileSync(path.join(source, "package.json"), "utf8")).version; + if (sarif.version !== "2.1.0" || sarif.runs[0].tool.driver.version !== version) + throw new Error("SARIF identity mismatch"); + runAction("low", "", 1); + runAction("high", "--unknown-option", 2); + const optimizeOutput = runAction("critical", "", 0, "optimize"); + const optimize = JSON.parse( + readFileSync(path.join(optimizeOutput, "ackit-findings.json"), "utf8"), + ); + if (optimize.suggestions.length === 0) + throw new Error("Optimize fixture produced no suggestions"); + const optimizeSarif = JSON.parse(readFileSync(path.join(optimizeOutput, "ackit.sarif"), "utf8")); + if (optimizeSarif.runs[0].results.length !== optimize.suggestions.length) + throw new Error("Optimize SARIF projection missing suggestions"); + const cliOptimizeSarif = JSON.parse( + run( + process.execPath, + [path.join(source, "dist/cli/index.js"), "optimize", "--format", "sarif"], + { cwd: consumer }, + ), + ); + if (JSON.stringify(cliOptimizeSarif) !== JSON.stringify(optimizeSarif)) + throw new Error("CLI/Action optimize SARIF mismatch"); + runAction("low", "", 1, "optimize"); + runAction("critical", "--unknown-option", 2, "optimize"); + runAction("critical", "check-active --ci", 0, "drift"); + writeFileSync(path.join(consumer, ".gitignore"), ".ackit/\n"); + run("git", ["config", "user.name", "fixture"], { cwd: consumer }); + run("git", ["config", "user.email", "fixture@example.invalid"], { cwd: consumer }); + run("git", ["add", "."], { cwd: consumer }); + run("git", ["-c", "commit.gpgsign=false", "commit", "-qm", "test: fixture baseline"], { + cwd: consumer, + }); + const task = JSON.parse( + run( + process.execPath, + [ + path.join(source, "dist/cli/index.js"), + "--json", + "task", + "create", + "consumer drift fixture", + ], + { cwd: consumer }, + ), + ); + const taskFile = path.join(consumer, task.file); + const header = /^---\r?\n[\s\S]*?\r?\n---/.exec(readFileSync(taskFile, "utf8"))?.[0]; + if (!header) throw new Error("Generated task header missing"); + writeFileSync( + taskFile, + `${header}\n\n## Affected files\n\n- src/**\n\n## Acceptance criteria\n\n- [ ] fixture\n\n## Completion notes\n\nFixture remains pending.\n`, + ); + writeFileSync(path.join(consumer, "UNPLANNED.md"), "# Fixture drift\n"); + const driftOutput = runAction("critical", `check ${task.created}`, 0, "drift"); + const drift = JSON.parse(readFileSync(path.join(driftOutput, "ackit-findings.json"), "utf8")); + if (drift.findings.length === 0) throw new Error("Drift fixture produced no findings"); + runAction("low", `check ${task.created}`, 1, "drift"); + runAction( + "critical", + `check ${task.created} --ci`, + drift.findings.some((finding) => finding.severity === "blocking") ? 1 : 0, + "drift", + ); + if (existsSync(path.join(consumer, "node_modules")) || existsSync(path.join(consumer, "dist"))) + throw new Error("Consumer must not supply runtime"); + console.log( + `Action external-consumer PASS (${version}; clean source, scan/optimize/drift thresholds, CLI errors, SARIF)`, + ); +} finally { + rmSync(work, { recursive: true, force: true }); +} diff --git a/scripts/action-package-path.mjs b/scripts/action-package-path.mjs new file mode 100644 index 00000000..77e8e12a --- /dev/null +++ b/scripts/action-package-path.mjs @@ -0,0 +1,19 @@ +import { readFileSync, realpathSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +// pnpm/action-setup resolves package_json_file with path.join(workspace, input). +// Always target this Action's manifest, including when the consumer is elsewhere. +const actionRoot = process.env.ACKIT_ACTION_PATH ?? fileURLToPath(new URL("../", import.meta.url)); +const workspace = realpathSync(process.env.GITHUB_WORKSPACE ?? process.cwd()); +const manifest = realpathSync(path.join(actionRoot, "package.json")); +const pkg = JSON.parse(readFileSync(manifest, "utf8")); +if ( + typeof pkg.packageManager !== "string" || + !/^pnpm@\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+\S+)?$/.test(pkg.packageManager) +) + throw new Error("Action packageManager must pin an exact pnpm version"); +const relative = path.relative(workspace, manifest); +if (!relative || path.isAbsolute(relative)) + throw new Error("Action manifest must be workspace-relative for pnpm setup"); +console.log(`path=${relative}`); diff --git a/scripts/check-version-parity.mjs b/scripts/check-version-parity.mjs index 3598d887..3b658565 100644 --- a/scripts/check-version-parity.mjs +++ b/scripts/check-version-parity.mjs @@ -379,11 +379,21 @@ export function checkParity(overrides = {}) { failures.push(`ci workflow unreadable: ${error.message}`); } if (ci !== "") { - if (!ci.includes(`'${source}'`)) { - failures.push(`.github/workflows/ci.yml manifest contract does not assert '${source}'`); + if ( + !ci.includes("node scripts/check-version-parity.mjs") || + !ci.includes("pkg.version!==root.version") + ) { + failures.push( + ".github/workflows/ci.yml must enforce dynamic extension/root version parity", + ); } - if (!ci.includes(`ackit-vscode-${source}.vsix`)) { - failures.push(`.github/workflows/ci.yml VSIX filename does not track '${source}'`); + if ( + !ci.includes("pkgver=$(node -p \"require('./extensions/vscode/package.json').version\")") || + !ci.includes('vsix="ackit-vscode-' + "$" + '{pkgver}.vsix"') + ) { + failures.push( + ".github/workflows/ci.yml VSIX filename must derive from the extension manifest", + ); } } } diff --git a/scripts/check-vsix.mjs b/scripts/check-vsix.mjs new file mode 100644 index 00000000..c44009eb --- /dev/null +++ b/scripts/check-vsix.mjs @@ -0,0 +1,143 @@ +#!/usr/bin/env node +// Inspect the actual VSIX portably, with bounded ZIP extraction and CRC checks. +import { createHash } from "node:crypto"; +import { readFileSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { inflateRawSync } from "node:zlib"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +const file = process.argv[2]; +if (!file) throw new Error("Usage: node scripts/check-vsix.mjs "); +const zip = readFileSync(file); +if (zip.length > 2_097_152) throw new Error("VSIX exceeds 2 MB"); +const eocd = zip.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06])); +if (eocd < 0 || eocd < zip.length - 65_557 || eocd + 22 > zip.length) + throw new Error("Invalid ZIP directory"); +if (zip.readUInt16LE(eocd + 4) || zip.readUInt16LE(eocd + 6)) throw new Error("Split ZIP refused"); +const count = zip.readUInt16LE(eocd + 10); +if (count > 3000) throw new Error("Too many VSIX entries"); +let offset = zip.readUInt32LE(eocd + 16); +let total = 0; +const entries = new Map(); +const crcTable = Array.from({ length: 256 }, (_, index) => { + let value = index; + for (let bit = 0; bit < 8; bit++) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1; + return value >>> 0; +}); +const crc32 = (bytes) => { + let crc = 0xffffffff; + for (const byte of bytes) crc = crcTable[(crc ^ byte) & 255] ^ (crc >>> 8); + return (crc ^ 0xffffffff) >>> 0; +}; + +for (let index = 0; index < count; index++) { + if (offset + 46 > eocd || zip.readUInt32LE(offset) !== 0x02014b50) + throw new Error("Invalid ZIP entry"); + const flags = zip.readUInt16LE(offset + 8); + const method = zip.readUInt16LE(offset + 10); + const compressed = zip.readUInt32LE(offset + 20); + const size = zip.readUInt32LE(offset + 24); + const nameLength = zip.readUInt16LE(offset + 28); + const extraLength = zip.readUInt16LE(offset + 30); + const commentLength = zip.readUInt16LE(offset + 32); + const local = zip.readUInt32LE(offset + 42); + const end = offset + 46 + nameLength + extraLength + commentLength; + if (end > eocd) throw new Error("Truncated ZIP entry"); + const name = zip + .subarray(offset + 46, offset + 46 + nameLength) + .toString("utf8") + .toLowerCase(); + if ( + !name || + name.includes("\\") || + name.startsWith("/") || + name.split("/").some((part) => part === "." || part === "..") || + entries.has(name) + ) + throw new Error("Unsafe/duplicate VSIX path"); + total += size; + if (flags & 1 || ![0, 8].includes(method) || size > 4_194_304 || total > 16_777_216) + throw new Error("Unsupported/oversized ZIP entry"); + if (local + 30 > offset || zip.readUInt32LE(local) !== 0x04034b50) + throw new Error("Invalid ZIP local header"); + const start = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28); + if (start + compressed > offset) throw new Error("Invalid ZIP payload bounds"); + const payload = zip.subarray(start, start + compressed); + const bytes = + method === 8 ? inflateRawSync(payload, { maxOutputLength: Math.max(1, size) }) : payload; + if (bytes.length !== size || crc32(bytes) !== zip.readUInt32LE(offset + 16)) + throw new Error("VSIX CRC/size mismatch"); + if (/(^|\/)(node_modules|src|out|scripts|test-fixture)(\/|$)|\.(map|vsix)$/.test(name)) + throw new Error(`Unexpected packaged file: ${name}`); + entries.set(name, bytes); + offset = end; +} + +function content(name) { + const bytes = entries.get(name); + if (!bytes) throw new Error(`Required VSIX file missing: ${name}`); + return bytes.toString("utf8"); +} +const source = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")); +const extension = JSON.parse( + readFileSync(path.join(root, "extensions/vscode/package.json"), "utf8"), +); +const manifest = JSON.parse(content("extension/package.json")); +const sdk = JSON.parse(content("extension/dist/package.json")); +if ( + extension.version !== source.version || + manifest.version !== source.version || + sdk.version !== source.version +) + throw new Error("VSIX/source/SDK version mismatch"); +if ( + manifest.publisher !== "Cynrath" || + manifest.name !== "ackit-vscode" || + manifest.main !== "./dist/extension.js" || + sdk.name !== source.name || + sdk.type +) + throw new Error("VSIX identity/runtime mismatch"); +const xml = content("extension.vsixmanifest"); +const identity = /]+)>/.exec(xml)?.[1] ?? ""; +for (const [attribute, value] of Object.entries({ + Version: source.version, + Publisher: "Cynrath", + Id: "ackit-vscode", +})) { + if (new RegExp(`${attribute}="([^"]+)"`).exec(identity)?.[1] !== value) + throw new Error(`VSIX XML ${attribute} mismatch`); +} +const readme = content("extension/readme.md"); +if ( + /\*\*Version:\*\* `([^`]+)`/.exec(readme)?.[1] !== source.version || + /source checkouts build `([^`]+)`/.exec(readme)?.[1] !== source.version +) + throw new Error("VSIX README version mismatch"); +for (const marker of ["ackit.status.v1", "verification freshness", "checkpoint freshness"]) + if (!readme.toLowerCase().includes(marker)) throw new Error(`VSIX README missing ${marker}`); +if (/^## \[([^\]]+)\]/m.exec(content("extension/changelog.md"))?.[1] !== source.version) + throw new Error("VSIX CHANGELOG version mismatch"); +content("extension/dist/extension.js"); +for (const profile of ["codex", "claude", "copilot", "gemini", "generic"]) + content(`extension/dist/templates/profiles/${profile}.yml`); +content("extension/dist/templates/roles/verifier.yaml"); +const icon = entries.get("extension/images/icon.png"); +if ( + !icon || + icon.length <= 1024 || + icon.readUInt32BE(16) < 128 || + icon.readUInt32BE(16) !== icon.readUInt32BE(20) +) + throw new Error("Invalid VSIX icon"); +// A detector's header regex is not a key: require encoded material and footer. +const secrets = + /AKIA[0-9A-Z]{16}|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----\s+[A-Za-z0-9+/=\s]{32,}-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|gh[pousr]_[A-Za-z0-9]{32,}|sk-proj-[A-Za-z0-9_-]{20,}/; +for (const [name, bytes] of entries) { + if (/\.(js|json|md|yml|yaml|xml)$/.test(name) && secrets.test(bytes.toString("utf8"))) + throw new Error(`Credential pattern in ${name}`); +} +console.log( + `VSIX integrity PASS (${source.version}; ${entries.size} entries; ${zip.length} bytes; SHA-256 ${createHash("sha256").update(zip).digest("hex")})`, +); diff --git a/scripts/consumer-command.mjs b/scripts/consumer-command.mjs new file mode 100644 index 00000000..2936bb72 --- /dev/null +++ b/scripts/consumer-command.mjs @@ -0,0 +1,33 @@ +import { spawnSync } from "node:child_process"; +import { realpathSync } from "node:fs"; + +/** Bounded consumer-tool process boundary; never expose caller paths in errors. */ +export function runConsumerCommand(command, args, options = {}, redactions = []) { + const result = spawnSync(command, args, { + encoding: "utf8", + timeout: 180_000, + windowsHide: true, + ...options, + }); + if (result.status !== 0) { + let detail = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n"); + const aliases = redactions + .flatMap(([value, label]) => { + try { + return [ + [value, label], + [realpathSync(value), label], + ]; + } catch { + return [[value, label]]; + } + }) + .sort(([left], [right]) => right.length - left.length); + for (const [value, label] of aliases) detail = detail.replaceAll(value, label); + detail = detail.replace(/[A-Za-z]:[\\/][^\s"'<>]+/g, ""); + throw new Error( + `consumer command failed (exit ${result.status}): ${detail || "no command output"}`, + ); + } + return result.stdout; +} diff --git a/src/action/index.ts b/src/action/index.ts new file mode 100644 index 00000000..af3993f1 --- /dev/null +++ b/src/action/index.ts @@ -0,0 +1,5 @@ +#!/usr/bin/env node +import process from "node:process"; +import { runAction } from "./runtime.js"; + +process.exitCode = runAction(); diff --git a/src/action/runtime.ts b/src/action/runtime.ts new file mode 100644 index 00000000..d94023bb --- /dev/null +++ b/src/action/runtime.ts @@ -0,0 +1,209 @@ +import { spawnSync } from "node:child_process"; +import { appendFileSync, mkdirSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import process from "node:process"; +import { fileURLToPath } from "node:url"; +import { z } from "zod"; +import { + projectOptimizeSuggestions, + renderSarif, + type SarifFinding, +} from "../core/reporting/sarif.js"; +import { FindingSchema, SEVERITY_ORDER } from "../core/scanner/types.js"; + +const SuggestionSchema = z.object({ + id: z.string(), + category: z.string(), + severity: z.enum(["high", "medium", "low"]), + message: z.string(), + evidencePaths: z.array(z.string()), + evidence: z + .array(z.object({ relativePath: z.string(), line: z.number().int().positive().optional() })) + .optional(), +}); +const DriftFindingSchema = z.object({ + code: z.string(), + severity: z.enum(["blocking", "warning"]), + taskId: z.string(), + detail: z.string(), +}); + +function projectFindings(report: Record): SarifFinding[] { + if (report["schemaVersion"] === "ackit.drift-report.v1" && report["findings"] !== undefined) { + return DriftFindingSchema.array() + .parse(report["findings"]) + .map((finding) => ({ + ruleId: finding.code, + category: "task-docs-integrity", + severity: finding.severity === "blocking" ? "high" : "medium", + message: `${finding.taskId}: ${finding.detail}`, + evidence: "", + fingerprint: JSON.stringify([finding.code, finding.taskId, finding.detail]), + suppressed: false, + suppressionReason: null, + })); + } + if (report["findings"] !== undefined) return FindingSchema.array().parse(report["findings"]); + if (report["suggestions"] === undefined) return []; + return projectOptimizeSuggestions(SuggestionSchema.array().parse(report["suggestions"])); +} + +interface CliResult { + status: number | null; + stdout: string; + error?: Error | undefined; + signal?: NodeJS.Signals | null | undefined; +} + +interface ActionOptions { + env?: NodeJS.ProcessEnv; + /** Narrow process boundary for deterministic error/timeout regression tests. */ + invoke?: (args: string[]) => CliResult; + log?: (line: string) => void; + error?: (line: string) => void; +} + +/** Quoting groups argv only; no shell expansion or executable interpolation. */ +export function splitActionArgs(input: string): string[] { + const args: string[] = []; + let current = ""; + let quote: '"' | "'" | undefined; + let started = false; + for (const char of input) { + if (char === quote) { + quote = undefined; + } else if (quote === undefined && (char === '"' || char === "'")) { + quote = char; + started = true; + } else if (quote === undefined && /\s/.test(char)) { + if (started) args.push(current); + current = ""; + started = false; + } else { + current += char; + started = true; + } + } + if (quote !== undefined) throw new Error("Unclosed quote in Action args"); + if (started) args.push(current); + return args; +} + +function escapeCommand(value: string, property = false): string { + const escaped = value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A"); + return property ? escaped.replace(/:/g, "%3A").replace(/,/g, "%2C") : escaped; +} + +function input(env: NodeJS.ProcessEnv, name: string): string { + return ( + env[`INPUT_${name.toUpperCase().replaceAll("-", "_")}`] ?? + env[`INPUT_${name.toUpperCase()}`] ?? + "" + ); +} + +export function runAction(options: ActionOptions = {}): number { + const env = options.env ?? process.env; + const log = options.log ?? console.log; + const error = options.error ?? console.error; + let cliExit = 0; + try { + const command = input(env, "command") || "scan"; + const threshold = input(env, "fail-threshold") || "high"; + const rank = SEVERITY_ORDER.indexOf(threshold as (typeof SEVERITY_ORDER)[number]); + if (rank < 0) throw new Error("Invalid fail-threshold"); + const sarifInput = input(env, "upload-sarif"); + if (!["", "false", "true"].includes(sarifInput)) throw new Error("Invalid upload-sarif"); + const args = splitActionArgs(input(env, "args")); + const cliPath = fileURLToPath(new URL("../cli/index.js", import.meta.url)); + const invoke = + options.invoke ?? + ((argv: string[]): CliResult => + spawnSync(process.execPath, argv, { + encoding: "utf8", + env, + maxBuffer: 10 * 1024 * 1024, + timeout: 120_000, + windowsHide: true, + })); + const result = invoke([cliPath, command, ...args, "--json"]); + // A CLI error always wins; a successful process must never clear a threshold + // failure. Signals, timeouts and launch failures must fail closed as well. + cliExit = result.status ?? 1; + if (result.error || result.signal) { + error("::error::ACKit CLI did not complete (launch failure, signal or timeout)"); + return cliExit || 1; + } + if (!result.stdout.trim()) { + // The managed pre-commit entry intentionally succeeds silently when no + // active workflow task exists. Other report-producing commands fail closed. + if (cliExit === 0 && command === "drift" && args.includes("check-active")) return 0; + error(`::error::ACKit CLI returned no JSON report (exit ${cliExit})`); + return cliExit || 1; + } + const report: unknown = JSON.parse(result.stdout); + if (report === null || typeof report !== "object" || Array.isArray(report)) { + throw new Error("Invalid CLI JSON report"); + } + const payload = report as Record; + const requiredField = + command === "scan" || command === "drift" + ? "findings" + : command === "optimize" + ? "suggestions" + : undefined; + if (requiredField !== undefined && payload[requiredField] === undefined) + throw new Error("Missing command report findings"); + const findings = projectFindings(payload); + const activeFindings = findings.filter((finding) => !finding.suppressed); + const runnerTemp = env["RUNNER_TEMP"] || tmpdir(); + mkdirSync(runnerTemp, { recursive: true }); + const jsonPath = path.join(runnerTemp, "ackit-findings.json"); + const sarifPath = path.join(runnerTemp, "ackit.sarif"); + writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8"); + if (sarifInput === "true") writeFileSync(sarifPath, renderSarif(findings), "utf8"); + + const outputPath = env["GITHUB_OUTPUT"]; + if (outputPath) { + appendFileSync(outputPath, `findings-json=${jsonPath}\n`, "utf8"); + if (sarifInput === "true") appendFileSync(outputPath, `sarif-path=${sarifPath}\n`, "utf8"); + } + for (const finding of activeFindings.slice(0, 10)) { + const level = + finding.severity === "critical" || finding.severity === "high" + ? "error" + : finding.severity === "medium" + ? "warning" + : "notice"; + const location = finding.relativePath + ? ` file=${escapeCommand(finding.relativePath, true)},line=${finding.line ?? 1}` + : ""; + log(`::${level}${location}::${escapeCommand(`${finding.ruleId}: ${finding.message}`)}`); + } + const summaryPath = env["GITHUB_STEP_SUMMARY"]; + if (summaryPath) { + const rows = [...SEVERITY_ORDER] + .reverse() + .map( + (severity) => + `| ${severity} | ${activeFindings.filter((finding) => finding.severity === severity).length} |`, + ); + appendFileSync( + summaryPath, + `## ACKit โ€” ${activeFindings.length} active finding(s)\n\n` + + `| Severity | Count |\n|---|---|\n${rows.join("\n")}\n`, + "utf8", + ); + } + const exceeded = activeFindings.some( + (finding) => SEVERITY_ORDER.indexOf(finding.severity) >= rank, + ); + if (exceeded) error(`::error::fail-threshold ${threshold} exceeded`); + return cliExit || (exceeded ? 1 : 0); + } catch { + // Never expose raw child errors or report contents (paths/credentials) here. + error("::error::ACKit Action input, report or output processing failed"); + return cliExit || 1; + } +} diff --git a/src/api/scan-repository.ts b/src/api/scan-repository.ts index b912e75e..ebff2573 100644 --- a/src/api/scan-repository.ts +++ b/src/api/scan-repository.ts @@ -1,12 +1,14 @@ import type { RepositoryRoot } from "../core/filesystem/root.js"; import { runScan, type ScanPipelineOptions } from "../core/scanner/pipeline.js"; +import { defaultRegistry } from "../core/scanner/registry.js"; import type { ScanResult } from "../core/scanner/types.js"; import { AckitError } from "./errors.js"; /** * Scans a repository and returns the stable finding set (REQ-API-001). - * Thin alias over the internal pipeline with an API-friendly name; behavior - * is identical to `ackit scan` minus CLI concerns. + * Uses the same built-in catalog and pipeline as the CLI. Repository config + * and policy orchestration belong to the CLI/MCP layer; callers can supply + * explicit pipeline options and additional trusted rules here. * REQ-V020-J-002: typed errors (AckitError) + AbortSignal cancellation. */ export async function scanRepository( @@ -37,7 +39,7 @@ export async function scanRepository( const scanPromise = runScan(root, { ...(rest as ScanPipelineOptions), signal, - rules: [...extraRules], + rules: [...defaultRegistry.getAll(), ...extraRules], }); if (signal === undefined) return await scanPromise; return await Promise.race([scanPromise, abortedPromise]); diff --git a/src/cli/commands/optimize.ts b/src/cli/commands/optimize.ts index 8c4935fd..e2816ddb 100644 --- a/src/cli/commands/optimize.ts +++ b/src/cli/commands/optimize.ts @@ -3,9 +3,9 @@ import process from "node:process"; import { loadAckitConfig } from "../../core/config/index.js"; import { analyzeOptimize, applyFixes } from "../../core/context/index.js"; import { resolveRepositoryRoot } from "../../core/filesystem/root.js"; +import { projectOptimizeSuggestions, renderSarif } from "../../core/reporting/sarif.js"; import { emitDiagnostic } from "../../shared/diagnostics.js"; import { EXIT_CODES, type ExitCodeValue } from "../../shared/exit-codes.js"; -import { getPackageIdentity } from "../../shared/version.js"; import type { InstructionsCommandOptions } from "../context.js"; import { reportConfigErrors } from "./config.js"; @@ -142,28 +142,7 @@ export async function runOptimizeCommand( } if (fmt === "sarif") { - // Minimal SARIF 2.1.0 for optimize suggestions as results - const sarif = { - $schema: "https://json.schemastore.org/sarif-2.1.0.json", - version: "2.1.0", - runs: [ - { - tool: { driver: { name: "ackit", version: getPackageIdentity().version, rules: [] } }, - results: suggestions.map((s) => ({ - ruleId: s.id, - level: s.severity === "high" ? "error" : s.severity === "medium" ? "warning" : "note", - message: { text: s.message }, - locations: (s.evidence ?? []).map((e) => ({ - physicalLocation: { - artifactLocation: { uri: e.relativePath }, - region: e.line ? { startLine: e.line } : undefined, - }, - })), - })), - }, - ], - }; - process.stdout.write(`${JSON.stringify(sarif, null, 2)}\n`); + process.stdout.write(renderSarif(projectOptimizeSuggestions(suggestions))); return EXIT_CODES.ok; } diff --git a/src/cli/program.ts b/src/cli/program.ts index eca26412..69849cc5 100644 --- a/src/cli/program.ts +++ b/src/cli/program.ts @@ -373,8 +373,9 @@ function buildProgram(invocation: CliInvocation): Command { .command("serve") .description("serve the ACKit MCP server over stdio (protocol-pure stdout)") .action(async () => { - // Delegate to the dedicated entry so stdout carries only JSON-RPC. - await import("../mcp/stdio.js"); + // Bind the advertised startup root without reopening per-tool overrides. + const { serveAckitMcp } = await import("../mcp/stdio.js"); + await serveAckitMcp((program.opts() as Partial).root); // stdio entry keeps the process alive until the transport closes. return new Promise((resolve) => { process.on("exit", () => resolve()); diff --git a/src/core/reporting/sarif.ts b/src/core/reporting/sarif.ts index a97a8463..2a781801 100644 --- a/src/core/reporting/sarif.ts +++ b/src/core/reporting/sarif.ts @@ -1,6 +1,43 @@ import { getPackageIdentity } from "../../shared/version.js"; +import type { OptimizeSuggestion } from "../context/optimize.js"; import type { Finding } from "../scanner/types.js"; +/** Shared SARIF projection; optimizer categories are also valid properties. */ +export type SarifFinding = Omit< + Finding, + "category" | "remediation" | "documentationKey" | "relativePath" | "line" | "column" +> & { + category: string; + relativePath?: string; + line?: number; + column?: number; + remediation?: string; + documentationKey?: string; +}; + +type OptimizeSarifSource = Pick< + OptimizeSuggestion, + "id" | "severity" | "message" | "evidence" | "evidencePaths" +> & { category: string }; + +export function projectOptimizeSuggestions( + suggestions: readonly OptimizeSarifSource[], +): SarifFinding[] { + return suggestions.map((suggestion) => ({ + ruleId: suggestion.id, + category: suggestion.category, + severity: suggestion.severity, + message: suggestion.message, + relativePath: suggestion.evidence?.[0]?.relativePath ?? suggestion.evidencePaths[0], + line: suggestion.evidence?.[0]?.line ?? 1, + column: 1, + evidence: "", + fingerprint: suggestion.id, + suppressed: false, + suppressionReason: null, + })); +} + const SEVERITY_LEVEL: Record = { critical: "error", high: "error", @@ -14,7 +51,7 @@ const SEVERITY_LEVEL: Record = { * secret can appear (REQ-GOV-005). */ export function renderSarif( - findings: readonly Finding[], + findings: readonly SarifFinding[], options: { policyDigest?: string | undefined } = {}, ): string { const identity = getPackageIdentity(); @@ -32,14 +69,25 @@ export function renderSarif( message: { text: `${finding.message}${finding.evidence.length > 0 ? ` [evidence: ${finding.evidence}]` : ""}`, }, - locations: [ - { - physicalLocation: { - artifactLocation: { uri: finding.relativePath.split("\\").join("/") }, - region: { startLine: finding.line, startColumn: finding.column }, - }, - }, - ], + ...(finding.relativePath + ? { + locations: [ + { + physicalLocation: { + artifactLocation: { + uri: finding.relativePath + .split("\\") + .join("/") + .split("/") + .map(encodeURIComponent) + .join("/"), + }, + region: { startLine: finding.line ?? 1, startColumn: finding.column ?? 1 }, + }, + }, + ], + } + : {}), fingerprints: { "ackit/v1": finding.fingerprint }, properties: { severity: finding.severity, diff --git a/src/mcp/server.ts b/src/mcp/server.ts index cbb6e1c7..456b3eff 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -75,7 +75,9 @@ export async function createAckitMcpServer(requestedRoot?: string | undefined): signal: extra.signal, }); const reportJson = renderScanJson(executed.result); - return textResult(`${reportJson}\nexit_code_hint=${executed.exceededThreshold ? 1 : 0}`); + return textResult( + `${reportJson}\nexit_code_hint=${args.ci === true && executed.exceededThreshold ? 1 : 0}`, + ); } catch (error) { if (error instanceof ScanContractError || error instanceof GitUnavailableError) { return textResult( diff --git a/src/mcp/stdio.ts b/src/mcp/stdio.ts index 0f746787..52ef91af 100644 --- a/src/mcp/stdio.ts +++ b/src/mcp/stdio.ts @@ -1,11 +1,13 @@ #!/usr/bin/env node +import { realpathSync } from "node:fs"; // ACKit MCP stdio entry point (official SDK transport only; ADR-0008). import process from "node:process"; +import { fileURLToPath } from "node:url"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { createAckitMcpServer } from "./server.js"; -async function main(): Promise { - const { server } = await createAckitMcpServer(); +export async function serveAckitMcp(requestedRoot?: string): Promise { + const { server } = await createAckitMcpServer(requestedRoot); const transport = new StdioServerTransport(); await server.connect(transport); // Clean shutdown when stdio closes (REQ-MCP-004). @@ -14,8 +16,18 @@ async function main(): Promise { }); } -void main().catch((error: unknown) => { - // stdout must stay protocol-pure; diagnostics go to stderr only. - process.stderr.write(`ackit mcp: fatal ${(error as Error).message}\n`); - process.exitCode = 1; -}); +const invokedDirectly = (() => { + try { + const entry = process.argv[1]; + return entry !== undefined && realpathSync(entry) === fileURLToPath(import.meta.url); + } catch { + return false; + } +})(); + +if (invokedDirectly) + void serveAckitMcp().catch((error: unknown) => { + // stdout must stay protocol-pure; diagnostics go to stderr only. + process.stderr.write(`ackit mcp: fatal ${(error as Error).message}\n`); + process.exitCode = 1; + }); diff --git a/tests/contract/action-consumer-diagnostics.test.ts b/tests/contract/action-consumer-diagnostics.test.ts new file mode 100644 index 00000000..84242107 --- /dev/null +++ b/tests/contract/action-consumer-diagnostics.test.ts @@ -0,0 +1,79 @@ +import { execFile } from "node:child_process"; +import { mkdir, mkdtemp, realpath, rm, symlink } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { promisify } from "node:util"; +import { expect, it } from "vitest"; + +const execute = promisify(execFile); +it("a failed consumer install exposes stdout/status and remains a hard failure", async () => { + const dir = await mkdtemp(path.join(tmpdir(), "ackit-consumer-diagnostic-")); + try { + const childSource = + 'console.log("synthetic-install-cause " + process.cwd()); process.exitCode = 7;'; + const harness = ` + import { pathToFileURL } from "node:url"; + const { runConsumerCommand } = await import(pathToFileURL(process.argv[1]).href); + try { + runConsumerCommand(process.execPath, ["-e", ${JSON.stringify(childSource)}], + { cwd: process.argv[2] }, [[process.argv[2], ""]]); + } catch (error) { + console.error(error.message); + process.exitCode = 1; + } + `; + const result = await execute( + process.execPath, + ["--input-type=module", "-e", harness, path.resolve("scripts/consumer-command.mjs"), dir], + { + timeout: 20_000, + windowsHide: true, + }, + ).then( + () => ({ code: 0, stderr: "" }), + (error: { code: number; stderr: string }) => error, + ); + expect(result.code).toBe(1); + expect(result.stderr).toContain("consumer command failed (exit 7)"); + expect(result.stderr).toContain("synthetic-install-cause "); + expect(result.stderr).not.toContain(dir); + } finally { + expect(path.dirname(dir)).toBe(path.resolve(tmpdir())); + await rm(dir, { recursive: true, force: true }); + } +}); + +it("redacts both declared and canonical directory aliases", async () => { + const base = await mkdtemp(path.join(tmpdir(), "ackit-consumer-alias-")); + try { + const target = path.join(base, "actual"); + const alias = path.join(base, "alias"); + await mkdir(target); + await symlink(target, alias, process.platform === "win32" ? "junction" : "dir"); + const childSource = + 'console.log("synthetic-install-cause " + require("node:fs").realpathSync(process.cwd())); process.exitCode = 7;'; + const harness = ` + import { pathToFileURL } from "node:url"; + const { runConsumerCommand } = await import(pathToFileURL(process.argv[1]).href); + try { runConsumerCommand(process.execPath, ["-e", ${JSON.stringify(childSource)}], + { cwd: process.argv[2] }, [[process.argv[2], ""]]); } + catch (error) { console.error(error.message); process.exitCode = 1; } + `; + const result = await execute( + process.execPath, + ["--input-type=module", "-e", harness, path.resolve("scripts/consumer-command.mjs"), alias], + { timeout: 20_000, windowsHide: true }, + ).then( + () => ({ code: 0, stderr: "" }), + (error: { code: number; stderr: string }) => error, + ); + expect(result.code).toBe(1); + expect(result.stderr).toContain("consumer command failed (exit 7)"); + expect(result.stderr).toContain("synthetic-install-cause "); + expect(result.stderr).not.toContain(alias); + expect(result.stderr).not.toContain(await realpath(target)); + } finally { + expect(path.dirname(base)).toBe(path.resolve(tmpdir())); + await rm(base, { recursive: true, force: true }); + } +}); diff --git a/tests/contract/action-distribution.test.ts b/tests/contract/action-distribution.test.ts new file mode 100644 index 00000000..07344e47 --- /dev/null +++ b/tests/contract/action-distribution.test.ts @@ -0,0 +1,55 @@ +import { readFileSync } from "node:fs"; +import { describe, expect, it } from "vitest"; +import { parse } from "yaml"; + +interface ActionStep { + id?: string; + uses?: string; + run?: string; + env?: Record; + with?: Record; +} +const raw = readFileSync("action.yml", "utf8"); +const expression = (value: string): string => `$${"{"}{ ${value} }}`; +const action = parse(raw) as { + runs: { using: string; steps: ActionStep[] }; + outputs: Record; +}; + +describe("clean-tag Action distribution", () => { + it("bootstraps exact source with pinned setup actions and a frozen install", () => { + expect(action.runs.using).toBe("composite"); + for (const step of action.runs.steps.filter((step) => step.uses)) { + expect(step.uses).toMatch(/@[0-9a-f]{40}$/); + } + const setup = action.runs.steps.find((step) => step.uses?.startsWith("pnpm/action-setup@")); + expect(setup?.with?.["package_json_file"]).toBe( + expression("steps.action-package.outputs.path"), + ); + expect( + action.runs.steps.find((step) => step.id === "action-package")?.env?.["ACKIT_ACTION_PATH"], + ).toBe(expression("github.action_path")); + expect(raw).toContain("pnpm install --frozen-lockfile --ignore-scripts"); + expect(raw).toContain("pnpm build"); + expect(raw.indexOf("pnpm build")).toBeLessThan(raw.indexOf("/dist/action/index.js")); + }); + it("passes every untrusted input through env and maps real step outputs", () => { + for (const step of action.runs.steps) expect(step.run ?? "").not.toContain("${{ inputs."); + expect(action.runs.steps.at(-1)?.env?.["INPUT_ARGS"]).toBe(expression("inputs.args")); + expect(action.outputs["findings-json"]?.value).toBe( + expression("steps.ackit.outputs.findings-json"), + ); + expect(action.outputs["sarif-path"]?.value).toBe(expression("steps.ackit.outputs.sarif-path")); + }); + it("dogfood has no preparatory install/build that could hide missing runtime", () => { + const workflow = parse(readFileSync(".github/workflows/ackit-action-dogfood.yml", "utf8")) as { + jobs: { "action-smoke": { steps: ActionStep[] } }; + }; + const steps = workflow.jobs["action-smoke"].steps; + const index = steps.findIndex((step) => step.uses === "./"); + expect(index).toBeGreaterThan(0); + for (const step of steps.slice(0, index)) { + expect(step.run ?? "").not.toMatch(/pnpm (?:install|build)/); + } + }); +}); diff --git a/tests/contract/action-package-path.test.ts b/tests/contract/action-package-path.test.ts new file mode 100644 index 00000000..e2412957 --- /dev/null +++ b/tests/contract/action-package-path.test.ts @@ -0,0 +1,46 @@ +import { execFile } from "node:child_process"; +import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { promisify } from "node:util"; +import { expect, it } from "vitest"; + +const execute = promisify(execFile); +it("pnpm setup resolves the Action's pinned manifest from an unrelated consumer", async () => { + const base = await mkdtemp(path.join(tmpdir(), "ackit-action-manifest-")); + try { + const actionRoot = path.join(base, "action checkout"); + const workspace = path.join(base, "consumer workspace"); + await mkdir(actionRoot); + await mkdir(workspace); + const pinned = JSON.parse(await readFile("package.json", "utf8")).packageManager as string; + await writeFile( + path.join(actionRoot, "package.json"), + JSON.stringify({ packageManager: pinned }), + ); + await writeFile( + path.join(workspace, "package.json"), + JSON.stringify({ packageManager: "pnpm@1.0.0" }), + ); + for (const consumer of [workspace, actionRoot]) { + const result = await execute( + process.execPath, + [path.resolve("scripts/action-package-path.mjs")], + { + cwd: consumer, + env: { ...process.env, ACKIT_ACTION_PATH: actionRoot, GITHUB_WORKSPACE: consumer }, + timeout: 20_000, + windowsHide: true, + }, + ); + const relative = result.stdout.trim().slice("path=".length); + expect(path.isAbsolute(relative)).toBe(false); + const target = path.join(consumer, relative); // exact pinned setup resolution contract + expect(await realpath(target)).toBe(await realpath(path.join(actionRoot, "package.json"))); + expect(JSON.parse(await readFile(target, "utf8")).packageManager).toBe(pinned); + } + } finally { + expect(path.dirname(base)).toBe(path.resolve(tmpdir())); + await rm(base, { recursive: true, force: true }); + } +}); diff --git a/tests/contract/ci-pinning.test.ts b/tests/contract/ci-pinning.test.ts index 5cd04ae2..ba58b08d 100644 --- a/tests/contract/ci-pinning.test.ts +++ b/tests/contract/ci-pinning.test.ts @@ -62,6 +62,36 @@ describe("CI workflow hardening", () => { expect(raw).toContain("scan --ci"); expect(raw).toContain("smoke:package"); }); + + it("enforces schema/CLI/version gates and real extension failures", () => { + const doc = parse(raw) as { + jobs: Record; + }; + const runs = doc.jobs["verify"]?.steps.map((step) => step.run ?? "").join("\n") ?? ""; + for (const marker of [ + "pnpm gen:schemas", + "git diff --exit-code -- schemas", + "pnpm smoke:cli", + "node scripts/check-version-parity.mjs", + ]) + expect(runs).toContain(marker); + const extension = doc.jobs["extension"]?.steps ?? []; + for (const step of extension) { + expect(step["continue-on-error"]).not.toBe(true); + expect(step.run ?? "").not.toMatch(/\|\|\s*(?:true|echo)|--diagnostic-level=warn/); + } + const commands = extension.map((step) => step.run ?? "").join("\n"); + for (const marker of [ + "run lint", + "run typecheck", + "run test:unit", + "xvfb-run -a pnpm --filter ackit-vscode test", + "node scripts/check-vsix.mjs", + "pkg.version!==root.version", + ]) + expect(commands).toContain(marker); + expect(commands).not.toMatch(/ackit-vscode-\d+\.\d+\.\d+\.vsix/); + }); }); /** Controlled-release gate: release.yml must stay a tags-only, npm-OIDC + @@ -317,4 +347,16 @@ describe("release workflow hardening", () => { expect(raw).toContain("v" + "$" + "{RELEASE_VERSION}"); expect(raw).toContain("AgentContextKit v" + "$" + "{RELEASE_VERSION}" + " release"); }); + + it("bounds final Marketplace stale-read retries and still fails closed", () => { + const doc = parse(raw) as { jobs: { release: { steps: { name?: string; run?: string }[] } } }; + const final = doc.jobs.release.steps.at(-1); + expect(final?.name).toContain("Final public-surface verification"); + const run = final?.run ?? ""; + expect(run).toMatch(/for attempt in \$\(seq 1 6\); do/); + expect(run).toContain('if [ "' + "$" + '{attempt}" -lt 6 ]; then sleep 10; fi'); + expect(run).toContain('"' + "$" + '{MKT_FINAL}" = "' + "$" + '{RELEASE_VERSION}"'); + expect(run).toContain("exit 91"); + expect(run).not.toMatch(/\|\|\s*true|vsce.*publish/); + }); }); diff --git a/tests/contract/documentation-distribution.test.ts b/tests/contract/documentation-distribution.test.ts new file mode 100644 index 00000000..8042296c --- /dev/null +++ b/tests/contract/documentation-distribution.test.ts @@ -0,0 +1,46 @@ +import { existsSync, readFileSync } from "node:fs"; +import path from "node:path"; +import { describe, expect, it } from "vitest"; + +describe("maintained documentation distribution", () => { + it("README local Markdown links resolve to maintained files or directories", () => { + const markdown = readFileSync("README.md", "utf8"); + for (const match of markdown.matchAll(/\[[^\]]*\]\(]+)>?\)/g)) { + const target = (match[1] ?? "").split("#")[0] ?? ""; + if (!target || /^[a-z]+:/i.test(target)) continue; + expect(existsSync(path.resolve(decodeURIComponent(target))), target).toBe(true); + } + }); + it("every Docs7 navigation route has an actual page inside docs", () => { + const config = JSON.parse(readFileSync("docs/docs.json", "utf8")) as { + navigation: { groups: { pages: string[] }[] }; + }; + const root = path.resolve("docs"); + const routes = config.navigation.groups.flatMap((group) => group.pages); + expect(routes.length).toBeGreaterThan(0); + expect(new Set(routes).size).toBe(routes.length); + for (const route of routes) { + const absolute = path.resolve(root, route); + expect(absolute.startsWith(`${root}${path.sep}`), route).toBe(true); + expect( + [".md", ".mdx"].some((suffix) => existsSync(absolute + suffix)), + route, + ).toBe(true); + } + }); + it("Context7 indexing points to existing current documentation", () => { + const config = JSON.parse(readFileSync("context7.json", "utf8")) as { + projectTitle: string; + description: string; + folders: string[]; + rules: string[]; + excludeFolders: string[]; + }; + expect(config.projectTitle.length).toBeLessThanOrEqual(100); + expect(config.description.length).toBeLessThanOrEqual(500); + for (const rule of config.rules) expect(rule.length).toBeLessThanOrEqual(255); + for (const folder of config.folders) expect(existsSync(folder), folder).toBe(true); + expect(config.excludeFolders).toContain("docs/tasks"); + expect(config.excludeFolders).toContain("docs/rebuild"); + }); +}); diff --git a/tests/contract/mcp/tool-inputs.test.ts b/tests/contract/mcp/tool-inputs.test.ts new file mode 100644 index 00000000..d96e088a --- /dev/null +++ b/tests/contract/mcp/tool-inputs.test.ts @@ -0,0 +1,109 @@ +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; +import { describe, expect, it } from "vitest"; +import { createAckitMcpServer } from "../../../src/mcp/server.js"; + +async function session(options: { finding?: boolean; suppress?: boolean } = {}) { + const root = await mkdtemp(path.join(tmpdir(), "ackit-mcp-inputs-")); + await writeFile(path.join(root, "AGENTS.md"), "# Instructions\nReview repository checks.\n"); + await writeFile(path.join(root, "README.md"), "# Fixture\n"); + await writeFile( + path.join(root, "ackit.yml"), + "schemaVersion: 1\npolicy:\n extends: [ackit-policy.yml]\n", + ); + await writeFile( + path.join(root, "ackit-policy.yml"), + "schemaVersion: 1\nthresholds:\n severity: low\n" + + (options.suppress + ? [ + "suppressions:", + " - ruleId: ACKIT020", + " pathGlobs: [inside.txt]", + " reason: intentional fixture marker", + ' expiresAt: "2099-12-31"', + "", + ].join("\n") + : ""), + ); + if (options.finding) await writeFile(path.join(root, "inside.txt"), "TODO: fixture\n"); + const { server } = await createAckitMcpServer(root); + const client = new Client({ name: "input-contract", version: "0.0.1" }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + return { + client, + close: async () => { + await client.close(); + expect(path.dirname(root)).toBe(path.resolve(tmpdir())); + await rm(root, { recursive: true, force: true }); + }, + }; +} + +describe("MCP documented inputs and severity hints", () => { + it("the reference table matches all live tool schema properties", async () => { + const current = await session(); + try { + const reference = await readFile("docs/reference/mcp.md", "utf8"); + const rows = [...reference.matchAll(/^\| (ackit_[a-z_]+) \| ([^|]*) \|/gm)]; + const documented = new Map( + rows.map((row) => [ + row[1], + (row[2] ?? "").trim() === "โ€”" + ? [] + : (row[2] ?? "") + .split(",") + .map((arg) => arg.trim().replace(/\?$/, "")) + .sort(), + ]), + ); + const { tools } = await current.client.listTools(); + expect([...documented.keys()].sort()).toEqual(tools.map((tool) => tool.name).sort()); + for (const tool of tools) { + const properties = Object.keys(tool.inputSchema.properties ?? {}).sort(); + expect(properties, tool.name).toEqual(documented.get(tool.name)); + expect(properties).not.toContain("root"); + expect(properties).not.toContain("includeGlobs"); + } + } finally { + await current.close(); + } + }); + it.each([ + { ci: undefined, finding: true, suppress: false, hint: 0 }, + { ci: false, finding: true, suppress: false, hint: 0 }, + { ci: true, finding: true, suppress: false, hint: 1 }, + { ci: true, finding: false, suppress: false, hint: 0 }, + { ci: true, finding: true, suppress: true, hint: 0 }, + ])( + "ci=$ci finding=$finding suppress=$suppress hints $hint", + async ({ ci, finding, suppress, hint }) => { + const current = await session({ finding, suppress }); + try { + const result = await current.client.callTool({ + name: "ackit_scan", + arguments: ci === undefined ? {} : { ci }, + }); + expect(result.isError ?? false).toBe(false); + const text = (result.content as { type: string; text: string }[]) + .map((item) => item.text) + .join(""); + const [report, exitHint] = text.split("\nexit_code_hint="); + expect(exitHint).toBe(String(hint)); + const findings = ( + JSON.parse(report ?? "null") as { findings: { ruleId: string; suppressed: boolean }[] } + ).findings; + expect(findings.some((item) => item.ruleId === "ACKIT020")).toBe(finding); + if (suppress) + expect(findings.find((item) => item.ruleId === "ACKIT020")?.suppressed).toBe(true); + expect((await current.client.listTools()).tools.length).toBe(16); + } finally { + await current.close(); + } + }, + ); +}); diff --git a/tests/contract/version-parity.test.ts b/tests/contract/version-parity.test.ts index 8f2f8d44..1b5c8300 100644 --- a/tests/contract/version-parity.test.ts +++ b/tests/contract/version-parity.test.ts @@ -216,7 +216,7 @@ describe("version-parity guard probes (TASK-0078 A-E)", () => { const source = readSourceVersion(); const stable = readPublishedStable(); const extensionManifest = JSON.stringify({ version: source }); - const ci = `contract '${source}' and ackit-vscode-${source}.vsix`; + const ci = readTree()[".github/workflows/ci.yml"] ?? ""; const files: Record = {}; for (const file of CURRENT_FILES) { if (MUST_SHOW_STABLE.includes(file)) { @@ -295,6 +295,18 @@ describe("version-parity guard probes (TASK-0078 A-E)", () => { `expected a CHANGELOG parity failure, got: ${failures.join("; ")}`, ).toBe(true); }); + + it("rejects removed dynamic CI parity and literal VSIX filenames", () => { + const files = readTree(); + files[".github/workflows/ci.yml"] = "legacy literal version check and ackit-vscode-0.5.4.vsix"; + const { failures } = checkParity({ files }); + expect( + failures.some((failure) => failure.includes("dynamic extension/root version parity")), + ).toBe(true); + expect(failures.some((failure) => failure.includes("derive from the extension manifest"))).toBe( + true, + ); + }); }); describe("marketplace content parity helpers (TASK-0090)", () => { diff --git a/tests/contract/vsix-integrity.test.ts b/tests/contract/vsix-integrity.test.ts new file mode 100644 index 00000000..14544de0 --- /dev/null +++ b/tests/contract/vsix-integrity.test.ts @@ -0,0 +1,134 @@ +import { spawnSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { describe, expect, it } from "vitest"; + +const root = process.cwd(); +const source = JSON.parse(readFileSync("package.json", "utf8")) as { + name: string; + version: string; +}; +const extension = readFileSync("extensions/vscode/package.json"); +const table = Array.from({ length: 256 }, (_, index) => { + let value = index; + for (let bit = 0; bit < 8; bit++) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1; + return value >>> 0; +}); +function crc32(bytes: Buffer): number { + let crc = 0xffffffff; + for (const byte of bytes) crc = (table[(crc ^ byte) & 255] ?? 0) ^ (crc >>> 8); + return (crc ^ 0xffffffff) >>> 0; +} +// A tiny stored-entry ZIP fixture writer, independent of the inspected reader. +function archive(entries: Record): Buffer { + const payloads: Buffer[] = []; + const directory: Buffer[] = []; + let offset = 0; + for (const [name, value] of Object.entries(entries)) { + const filename = Buffer.from(name); + const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value); + const local = Buffer.alloc(30); + local.writeUInt32LE(0x04034b50, 0); + local.writeUInt16LE(20, 4); + local.writeUInt32LE(crc32(bytes), 14); + local.writeUInt32LE(bytes.length, 18); + local.writeUInt32LE(bytes.length, 22); + local.writeUInt16LE(filename.length, 26); + const central = Buffer.alloc(46); + central.writeUInt32LE(0x02014b50, 0); + central.writeUInt16LE(20, 4); + central.writeUInt16LE(20, 6); + central.writeUInt32LE(crc32(bytes), 16); + central.writeUInt32LE(bytes.length, 20); + central.writeUInt32LE(bytes.length, 24); + central.writeUInt16LE(filename.length, 28); + central.writeUInt32LE(offset, 42); + payloads.push(local, filename, bytes); + directory.push(central, filename); + offset += local.length + filename.length + bytes.length; + } + const end = Buffer.alloc(22); + end.writeUInt32LE(0x06054b50, 0); + end.writeUInt16LE(directory.length / 2, 8); + end.writeUInt16LE(directory.length / 2, 10); + end.writeUInt32LE(Buffer.concat(directory).length, 12); + end.writeUInt32LE(offset, 16); + return Buffer.concat([...payloads, ...directory, end]); +} +function fixture(): Record { + const entries: Record = { + "extension/package.json": extension, + "extension/dist/package.json": JSON.stringify({ name: source.name, version: source.version }), + "extension/dist/extension.js": "// bundled fixture\n", + "extension.vsixmanifest": ``, + "extension/readme.md": readFileSync("extensions/vscode/README.md"), + "extension/changelog.md": readFileSync("extensions/vscode/CHANGELOG.md"), + "extension/images/icon.png": readFileSync("extensions/vscode/images/icon.png"), + "extension/dist/templates/roles/verifier.yaml": readFileSync("templates/roles/verifier.yaml"), + }; + for (const name of ["codex", "claude", "copilot", "gemini", "generic"]) { + entries[`extension/dist/templates/profiles/${name}.yml`] = readFileSync( + `templates/profiles/${name}.yml`, + ); + } + return entries; +} +async function check(bytes: Buffer): Promise<{ code: number | null; output: string }> { + const dir = await mkdtemp(path.join(tmpdir(), "ackit-vsix-contract-")); + try { + const file = path.join(dir, "fixture.vsix"); + await writeFile(file, bytes); + const result = spawnSync(process.execPath, ["scripts/check-vsix.mjs", file], { + cwd: root, + encoding: "utf8", + timeout: 10_000, + windowsHide: true, + }); + return { code: result.status, output: result.stdout + result.stderr }; + } finally { + expect(path.dirname(dir)).toBe(path.resolve(tmpdir())); + await rm(dir, { recursive: true, force: true }); + } +} + +describe("packaged VSIX fail-closed integrity gate", () => { + it("accepts version-coupled content and detector text without key material", async () => { + const entries = fixture(); + entries["extension/dist/extension.js"] = `/${["-----BEGIN", "PRIVATE KEY-----"].join(" ")}/g;`; + expect((await check(archive(entries))).code).toBe(0); + }); + it("rejects version drift and missing bundled resources", async () => { + const drift = fixture(); + drift["extension/dist/package.json"] = JSON.stringify({ ...source, version: "0.0.0" }); + expect((await check(archive(drift))).output).toContain("version mismatch"); + const missing = fixture(); + delete missing["extension/dist/templates/profiles/codex.yml"]; + expect((await check(archive(missing))).output).toContain("profiles/codex.yml"); + }); + it.each([ + "extension/node_modules/a.js", + "extension/dist/extension.js.map", + "extension/src/a.ts", + "../outside.txt", + ])("rejects unexpected path %s", async (file) => { + expect((await check(archive({ ...fixture(), [file]: "unexpected" }))).code).not.toBe(0); + }); + it("rejects actual credential-shaped material and corrupted payloads", async () => { + const entries = fixture(); + entries["extension/dist/extension.js"] = [ + ["-----BEGIN", "PRIVATE KEY-----"].join(" "), + "A".repeat(64), + ["-----END", "PRIVATE KEY-----"].join(" "), + ].join("\n"); + expect((await check(archive(entries))).output).toContain("Credential pattern"); + entries["extension/dist/extension.js"] = ["gh", "p_"].join("") + "a".repeat(36); + expect((await check(archive(entries))).output).toContain("Credential pattern"); + const corrupt = archive(fixture()); + const index = corrupt.indexOf(extension); + expect(index).toBeGreaterThan(0); + corrupt[index] = (corrupt[index] ?? 0) ^ 1; + expect((await check(corrupt)).output).toContain("CRC/size mismatch"); + }); +}); diff --git a/tests/integration/context/pack.test.ts b/tests/integration/context/pack.test.ts index 5ca17d09..603ce5d2 100644 --- a/tests/integration/context/pack.test.ts +++ b/tests/integration/context/pack.test.ts @@ -7,7 +7,7 @@ import { buildContextPack, RANKING_WEIGHTS } from "../../../src/core/context/pac let repo: { rootPath: string; cleanup(): Promise }; const SECRET_VALUE = "AKIAIOSFODNN7EXAMPLE"; -const WIN_ABS = "C:\\Users\\gizem\\AppData\\Local\\Temp\\cache"; +const WIN_ABS = "C:\\Users\\fixture-user\\AppData\\Local\\Temp\\cache"; beforeAll(async () => { const rootPath = await mkdtemp(path.join(tmpdir(), "ackit-pack-")); @@ -54,7 +54,7 @@ describe("context pack engine (REQ-CTX-001..004)", () => { it("scrubs machine-local absolute paths out of emitted content (Windows-style)", async () => { const result = await pack(); - expect(result.markdown).not.toContain("C:\\Users\\gizem"); + expect(result.markdown).not.toContain("C:\\Users\\fixture-user"); expect(result.markdown).toContain(""); const scrubbedEntry = result.manifest.find((item) => item.relativePath === "notes.md"); expect(scrubbedEntry?.action).toBe("scrubbed"); diff --git a/tests/integration/mcp/startup-root.test.ts b/tests/integration/mcp/startup-root.test.ts new file mode 100644 index 00000000..7fb80c4b --- /dev/null +++ b/tests/integration/mcp/startup-root.test.ts @@ -0,0 +1,59 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; +import { describe, expect, it } from "vitest"; + +const cli = path.join(process.cwd(), "dist/cli/index.js"); + +describe("CLI MCP startup root precedence", () => { + it.each(["flag", "environment", "cwd"])( + "uses the %s root without a per-call override", + async (mode) => { + const fixture = await mkdtemp(path.join(tmpdir(), "ackit-mcp-startup-")); + const selected = path.join(fixture, "selected repository"); + const working = path.join(fixture, "working repository"); + await mkdir(selected); + await mkdir(working); + for (const [root, name] of [ + [selected, "selected.txt"], + [working, "working.txt"], + ] as const) { + await writeFile(path.join(root, "AGENTS.md"), "# Instructions\nReview checks.\n"); + await writeFile(path.join(root, name), "TODO: fixture\n"); + } + const env = Object.fromEntries( + ["PATH", "SystemRoot", "WINDIR", "TEMP", "TMP"].flatMap((key) => { + const value = process.env[key]; + return value === undefined ? [] : [[key, value]]; + }), + ); + if (mode !== "cwd") env["ACKIT_ROOT"] = mode === "flag" ? working : selected; + const transport = new StdioClientTransport({ + command: process.execPath, + args: [cli, ...(mode === "flag" ? ["--root", selected] : []), "mcp", "serve"], + cwd: working, + env, + stderr: "pipe", + }); + const client = new Client({ name: "startup-root-test", version: "0.0.1" }); + try { + await client.connect(transport); + const result = await client.callTool({ name: "ackit_scan", arguments: {} }); + expect(result.isError ?? false).toBe(false); + const text = (result.content as { text: string }[]).map((item) => item.text).join(""); + const report = JSON.parse(text.split("\nexit_code_hint=")[0] ?? "null") as { + findings: { relativePath: string }[]; + }; + const paths = report.findings.map((finding) => finding.relativePath); + expect(paths).toContain(mode === "cwd" ? "working.txt" : "selected.txt"); + expect(paths).not.toContain(mode === "cwd" ? "selected.txt" : "working.txt"); + } finally { + await client.close(); + expect(path.dirname(fixture)).toBe(path.resolve(tmpdir())); + await rm(fixture, { recursive: true, force: true }); + } + }, + ); +}); diff --git a/tests/integration/sdk-example.test.ts b/tests/integration/sdk-example.test.ts new file mode 100644 index 00000000..af4c3097 --- /dev/null +++ b/tests/integration/sdk-example.test.ts @@ -0,0 +1,24 @@ +import { execFile } from "node:child_process"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { promisify } from "node:util"; +import { expect, it } from "vitest"; + +const execute = promisify(execFile); +it("the documented SDK consumer runs against an unrelated repository fixture", async () => { + const root = await mkdtemp(path.join(tmpdir(), "ackit-sdk-example-")); + try { + await writeFile(path.join(root, "sample.txt"), "TODO: fixture\n"); + const result = await execute(process.execPath, [path.resolve("examples/sdk-consumer.mjs")], { + cwd: root, + timeout: 20_000, + windowsHide: true, + }); + expect(result.stdout).toContain("sdk-consumer: findings=1 filesScanned=1"); + expect(result.stderr).toBe(""); + } finally { + expect(path.dirname(root)).toBe(path.resolve(tmpdir())); + await rm(root, { recursive: true, force: true }); + } +}); diff --git a/tests/integration/sdk-scan.test.ts b/tests/integration/sdk-scan.test.ts new file mode 100644 index 00000000..8f273a08 --- /dev/null +++ b/tests/integration/sdk-scan.test.ts @@ -0,0 +1,44 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { describe, expect, it } from "vitest"; +import type { ScanRule } from "../../src/core/scanner/types.js"; +import { scanRepository } from "../../src/index.js"; + +describe("SDK scan built-in catalog contract", () => { + it("runs built-in rules by default and appends extra rules", async () => { + const dir = await mkdtemp(path.join(tmpdir(), "ackit-sdk-catalog-")); + try { + await writeFile(path.join(dir, "sample.txt"), "TODO: review custom-marker\n"); + const baseline = await scanRepository({ canonicalPath: dir }); + expect(baseline.findings.some((finding) => finding.ruleId === "ACKIT020")).toBe(true); + const custom: ScanRule = { + id: "CUSTOM001", + severity: "low", + category: "hygiene", + documentationKey: "rules/CUSTOM001", + remediation: "Review custom marker", + appliesTo: (file) => file === "sample.txt", + evaluate: () => [ + { + ruleId: "CUSTOM001", + severity: "low", + category: "hygiene", + message: "Custom rule ran", + offset: 0, + rawEvidence: "custom-marker", + remediation: "Review custom marker", + documentationKey: "rules/CUSTOM001", + }, + ], + }; + const extended = await scanRepository({ canonicalPath: dir }, { extraRules: [custom] }); + expect(extended.findings.filter((finding) => finding.ruleId !== "CUSTOM001")).toEqual( + baseline.findings, + ); + expect(extended.findings.some((finding) => finding.ruleId === "CUSTOM001")).toBe(true); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/tests/security/secrets/secrets.test.ts b/tests/security/secrets/secrets.test.ts index 9ef24eb2..c4470d9f 100644 --- a/tests/security/secrets/secrets.test.ts +++ b/tests/security/secrets/secrets.test.ts @@ -45,7 +45,7 @@ beforeAll(async () => { // Absolute path leakage. await writeFile( path.join(r, "notes.md"), - "Build cache lives at C:\\Users\\gizem\\AppData\\Local\\Temp\\build\n", + "Build cache lives at C:\\Users\\fixture-user\\AppData\\Local\\Temp\\build\n", "utf8", ); // Unpinned workflow action. diff --git a/tests/unit/action/runtime.test.ts b/tests/unit/action/runtime.test.ts new file mode 100644 index 00000000..1c452c3d --- /dev/null +++ b/tests/unit/action/runtime.test.ts @@ -0,0 +1,255 @@ +import { mkdtemp, readFile, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { runAction, splitActionArgs } from "../../../src/action/runtime.js"; +import type { Finding } from "../../../src/core/scanner/types.js"; +import { getPackageIdentity } from "../../../src/shared/version.js"; + +const dirs: string[] = []; +afterEach(async () => { + for (const dir of dirs.splice(0)) await rm(dir, { recursive: true, force: true }); +}); + +function finding(overrides: Partial = {}): Finding { + return { + ruleId: "ACKIT020", + severity: "low", + category: "hygiene", + message: "Review marker", + relativePath: "sample.txt", + line: 2, + column: 1, + fingerprint: "fixture", + evidence: "", + remediation: "Review", + documentationKey: "rules/ACKIT020", + suppressed: false, + suppressionReason: null, + ...overrides, + }; +} + +async function execute( + findings: Finding[], + options: { + status?: number | null; + threshold?: string; + error?: Error; + signal?: NodeJS.Signals; + stdout?: string; + sarif?: string; + args?: string; + command?: string; + } = {}, +) { + const dir = await mkdtemp(path.join(tmpdir(), "ackit-action-test-")); + dirs.push(dir); + const messages: string[] = []; + let argv: string[] = []; + const code = runAction({ + env: { + RUNNER_TEMP: dir, + GITHUB_OUTPUT: path.join(dir, "outputs"), + GITHUB_STEP_SUMMARY: path.join(dir, "summary"), + INPUT_FAIL_THRESHOLD: options.threshold ?? "high", + INPUT_UPLOAD_SARIF: options.sarif ?? "true", + INPUT_ARGS: options.args ?? "", + INPUT_COMMAND: options.command ?? "scan", + }, + invoke: (args) => { + argv = args; + return { + status: options.status === undefined ? 0 : options.status, + stdout: options.stdout ?? JSON.stringify({ findings }), + error: options.error, + signal: options.signal, + }; + }, + log: (message) => messages.push(message), + error: (message) => messages.push(message), + }); + return { dir, code, messages, argv }; +} + +describe("Action threshold and process contract", () => { + it("applies thresholds to optimize suggestions and preserves their report", async () => { + const report = { + schemaVersion: "ackit.optimize.v0", + suggestions: [ + { + id: "OPT-DUPLICATE", + category: "redundant-content", + severity: "high", + message: "Duplicate instructions", + evidencePaths: ["AGENTS.md"], + evidence: [{ relativePath: "AGENTS.md", line: 3 }], + remediation: "Deduplicate", + fixable: false, + }, + ], + }; + const result = await execute([], { command: "optimize", stdout: JSON.stringify(report) }); + expect(result.code).toBe(1); + expect( + JSON.parse(await readFile(path.join(result.dir, "ackit-findings.json"), "utf8")), + ).toEqual(report); + const sarif = JSON.parse(await readFile(path.join(result.dir, "ackit.sarif"), "utf8")); + expect(sarif.runs[0].results[0].ruleId).toBe("OPT-DUPLICATE"); + expect(sarif.runs[0].results[0].properties.category).toBe("redundant-content"); + expect(sarif.runs[0].results[0].locations[0].physicalLocation).toEqual({ + artifactLocation: { uri: "AGENTS.md" }, + region: { startLine: 3, startColumn: 1 }, + }); + }); + it("fails at the threshold even when the CLI returns zero", async () => { + expect((await execute([finding({ severity: "high" })])).code).toBe(1); + }); + it.each([ + { severity: "low", status: 0, expected: 0 }, + { severity: "high", status: 0, expected: 1 }, + { severity: "high", status: 4, expected: 4 }, + ])( + "optimize severity=$severity CLI=$status exits $expected", + async ({ severity, status, expected }) => { + const report = { + suggestions: [ + { + id: "OPT", + category: "missing-task-docs", + severity, + message: "Missing tasks", + evidencePaths: ["docs/tasks"], + }, + ], + }; + expect( + (await execute([], { command: "optimize", status, stdout: JSON.stringify(report) })).code, + ).toBe(expected); + }, + ); + it("encodes SARIF path segments without changing the original JSON path", async () => { + const relativePath = "docs/a #rรฉsumรฉ?.md"; + const { dir } = await execute([finding({ relativePath })]); + const sarif = JSON.parse(await readFile(path.join(dir, "ackit.sarif"), "utf8")); + expect(sarif.runs[0].results[0].locations[0].physicalLocation.artifactLocation.uri).toBe( + "docs/a%20%23r%C3%A9sum%C3%A9%3F.md", + ); + const report = JSON.parse(await readFile(path.join(dir, "ackit-findings.json"), "utf8")); + expect(report.findings[0].relativePath).toBe(relativePath); + }); + it.each([ + { severity: "warning", threshold: "high", status: 0, expected: 0 }, + { severity: "blocking", threshold: "high", status: 0, expected: 1 }, + { severity: "blocking", threshold: "critical", status: 1, expected: 1 }, + ])( + "preserves drift $severity report and CLI=$status", + async ({ severity, threshold, status, expected }) => { + const report = { + schemaVersion: "ackit.drift-report.v1", + findings: [ + { + code: "DRIFT-SCOPE", + severity, + taskId: "TASK-0001", + detail: "Fixture drift", + }, + ], + }; + const result = await execute([], { + command: "drift", + threshold, + status, + stdout: JSON.stringify(report), + }); + expect(result.code).toBe(expected); + expect( + JSON.parse(await readFile(path.join(result.dir, "ackit-findings.json"), "utf8")), + ).toEqual(report); + const sarif = JSON.parse(await readFile(path.join(result.dir, "ackit.sarif"), "utf8")); + expect(sarif.runs[0].results[0].ruleId).toBe("DRIFT-SCOPE"); + expect(sarif.runs[0].results[0].message.text).toContain("Fixture drift"); + expect(sarif.runs[0].results[0]).not.toHaveProperty("locations"); + }, + ); + it("passes below threshold and when no findings exist", async () => { + expect((await execute([finding()])).code).toBe(0); + expect((await execute([])).code).toBe(0); + }); + it("honors policy suppression without hiding the report", async () => { + const result = await execute([finding({ severity: "critical", suppressed: true })]); + expect(result.code).toBe(0); + expect(result.messages).toEqual([]); + expect( + JSON.parse(await readFile(path.join(result.dir, "ackit-findings.json"), "utf8")).findings[0] + .suppressed, + ).toBe(true); + }); + it.each([1, 2, 3, 4, 5])("preserves CLI code %i even with a parsed report", async (status) => { + expect((await execute([finding({ severity: "critical" })], { status })).code).toBe(status); + }); + it("fails closed on launch error, timeout, signal, empty or malformed JSON", async () => { + for (const options of [ + { status: null, error: new Error("synthetic timeout") }, + { status: null, signal: "SIGTERM" as const }, + { stdout: "" }, + { stdout: "malformed" }, + { stdout: "[]" }, + ]) + expect((await execute([], options)).code).not.toBe(0); + }); + it("preserves drift check-active's successful empty legacy no-op", async () => { + const result = await execute([], { command: "drift", args: "check-active --ci", stdout: "" }); + expect(result.code).toBe(0); + expect(result.messages).toEqual([]); + await expect(readFile(path.join(result.dir, "outputs"))).rejects.toMatchObject({ + code: "ENOENT", + }); + }); + it.each(["scan", "optimize", "drift"])( + "fails closed if %s JSON omits its finding array", + async (command) => { + expect((await execute([], { command, stdout: "{}" })).code).not.toBe(0); + }, + ); + it("rejects invalid threshold, boolean and quoting before invoking CLI", async () => { + for (const options of [{ threshold: "hgh" }, { sarif: "yes" }, { args: '"unclosed' }]) { + const result = await execute([], options); + expect(result.code).not.toBe(0); + expect(result.argv).toEqual([]); + } + }); + it("uses the canonical SARIF 2.1.0 writer and actual package identity", async () => { + const { dir } = await execute([finding({ relativePath: "src\\sample.ts" })]); + const sarif = JSON.parse(await readFile(path.join(dir, "ackit.sarif"), "utf8")); + expect(sarif.version).toBe("2.1.0"); + expect(sarif.runs[0].tool.driver.version).toBe(getPackageIdentity().version); + expect(sarif.runs[0].results[0].locations[0].physicalLocation).toEqual({ + artifactLocation: { uri: "src/sample.ts" }, + region: { startLine: 2, startColumn: 1 }, + }); + expect(await readFile(path.join(dir, "outputs"), "utf8")).toContain("sarif-path="); + }); + it("does not advertise a SARIF output when it was not produced", async () => { + const { dir } = await execute([], { sarif: "false" }); + expect(await readFile(path.join(dir, "outputs"), "utf8")).not.toContain("sarif-path="); + await expect(readFile(path.join(dir, "ackit.sarif"))).rejects.toMatchObject({ code: "ENOENT" }); + }); + it("escapes annotation property delimiters and workflow command newlines", async () => { + const result = await execute([ + finding({ relativePath: "a,b:c\nfile.txt", message: "first\n::error::fake" }), + ]); + expect(result.messages[0]).toContain("file=a%2Cb%3Ac%0Afile.txt"); + expect(result.messages[0]).toContain("first%0A::error::fake"); + expect(result.messages[0]).not.toContain("\n"); + }); + it("passes metacharacters as literal argv, without shell evaluation", async () => { + const result = await execute([], { args: '"$(echo unsafe)" "; echo unsafe"' }); + expect(result.argv.slice(2, -1)).toEqual(["$(echo unsafe)", "; echo unsafe"]); + expect(splitActionArgs('--root "directory with spaces"\t--quiet')).toEqual([ + "--root", + "directory with spaces", + "--quiet", + ]); + }); +});