worclaude 2.5.1 → 2.6.1

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.6.1] — 2026-04-22
+
+Supply-chain scanner hygiene. Adds a `socket.yml` at the repo root so Socket (and any tool honoring the same schema) stops treating `tests/fixtures/scanner/**` manifests as real worclaude dependencies. The fixtures pin intentionally-outdated packages (`next@14.2.3`, `vitest@1.4.0`, `prisma@5.10.0`, etc.) as deterministic inputs to the Part A detectors — they are never installed (not referenced from root `package.json`), never shipped (`tests/` is excluded by the npm `files` whitelist), and never executed. Without the ignore, fixture deps surface on PR reviews as critical CVEs (CVE-2025-29927 Next.js middleware auth bypass, Vitest 1.4.0 RCE) that do not apply to worclaude. `SECURITY.md` is expanded with a "Supply Chain Scanner Findings" section documenting the fixture rationale, the real seven-package runtime dependency list, and the by-design `filesystemAccess` capability disclosure on `fs-extra`-heavy scaffolding code.
+
+### Added
+
+- **`socket.yml` at repo root** (PR #107) — `version: 2` schema with `projectIgnorePaths: [tests/fixtures/**]`. Respected by Socket's GitHub App on every PR review and by the Socket CLI's `socket scan create` command. Verified locally via `socket scan create --report`: manifests discovered drop from 21 to 6, scan verdict goes from unhealthy (2 critical + many high/medium false positives) to `healthy: true, alerts: 0` at warn level.
+
+### Changed
+
+- **`SECURITY.md` supported-versions row** bumped to `2.6.x` (from `2.4.x`) to reflect the current support window.
+
+### Docs
+
+- **`SECURITY.md` — Supply Chain Scanner Findings section** (PR #107) documents (1) why `tests/fixtures/scanner/**` manifests are not real dependencies, (2) worclaude's real seven-package runtime dep list, and (3) the `filesystemAccess` capability flag as a by-design disclosure for a scaffolding CLI rather than a vulnerability. Intended as a standing reference for any future SCA tool that surfaces the same false positives.
+
+## [2.6.0] — 2026-04-22
+
+Diagnose-first `/setup`. This release lands both halves of Phase Setup Diagnose in a single version: Part A (PR #103) ships the static project scanner and the new `worclaude scan` subcommand, and Part B (PR #104) rewrites `/setup` on top of it as a deterministic 12-state state machine with on-disk persistence, a tool-call whitelist, and a Claude-rendered selectable UI. Running `/setup` against a mature project now scans first (14 Tier 1 detectors produce a `DetectionReport`), presents the high-confidence facts as a numbered checklist for the user to confirm or uncheck, handles multi-candidate medium-confidence items (e.g., competing lockfiles), and only asks residual questions during the interview — cutting the interview from ~30 questions to whatever detection didn't cover. State survives interruption via `.claude/cache/setup-state.json`, persisted after every mutation through the new `worclaude setup-state` CLI (the sole write path `setup.md` is permitted to use under its tool whitelist). WRITE merges into existing output files conservatively: `CLAUDE.md` replaces `## Tech Stack` and `## Commands` sections by ATX heading; `SPEC.md` and SKILL files are rewritten only when template-only per CRLF-normalized SHA-256 match against `workflow-meta.json`, otherwise append a timestamped section; `PROGRESS.md` is append-only.
+
+### Added
+
+- **`worclaude scan` subcommand + detection engine** (PR #103, Part A) — new CLI subcommand that statically scans a project and produces a structured `DetectionReport` describing what it found. The report lands at `.claude/cache/detection-report.json` (machine-generated, gitignored, overwritten on every run). Ships 14 Tier 1 detectors under `src/core/project-scanner/detectors/` — one file per concern: `package-manager`, `language`, `frameworks`, `testing`, `linting`, `orm`, `deployment`, `ci`, `scripts`, `env-variables`, `external-apis`, `readme`, `spec-docs`, `monorepo`. Detector registration is directory-scan-based — adding a new detector means adding a new `.js` file, not editing the scanner. Each detector runs in parallel with a 5-second timeout; failures and timeouts are recorded in a per-report `errors` array without aborting the scan.
+- **CLI options for `scan`** (PR #103): `--path <dir>` (defaults to `process.cwd()`), `--json` (prints the full report to stdout, suppresses summary), `--quiet` (suppresses summary, still writes the cache file). Exit codes: `0` on any completed scan (even with per-detector errors), `1` on fatal errors (invalid path, un-writable cache).
+- **`pyproject.toml` dep flattening** (PR #103) — `frameworks`/`testing`/`linting`/`orm` detectors read all five dep locations (`[project.dependencies]`, `[project.optional-dependencies.*]`, `[tool.poetry.dependencies]`, `[tool.poetry.group.*.dependencies]`, `[dependency-groups.*]`) and flatten into a single map before matching. Fixtures exist for PEP 621, PEP 735, and Poetry-group layouts.
+- **Runtime dependencies** (PR #103): `smol-toml` (TOML parsing for `pyproject.toml`, `Cargo.toml`) and `yaml` (for `pnpm-workspace.yaml`, `Taskfile.yml`). Both are small, pure-JS, and zero-runtime-cost.
+- **`/setup` state machine rewrite** (PR #104, Part B) — `templates/commands/setup.md` is rewritten top-to-bottom as a 12-state state machine (`INIT → SCAN → CONFIRM_HIGH → CONFIRM_MEDIUM → INTERVIEW_STORY/ARCH/FEATURES/WORKFLOW/CONVENTIONS/VERIFICATION → WRITE → DONE`). `/setup` now invokes the Part A scanner at SCAN, presents detected facts via a Claude-rendered numbered checklist at CONFIRM_HIGH (user confirms or unchecks), handles multi-candidate medium-confidence items (`package-manager` with multiple lockfiles → numbered candidate list) at CONFIRM_MEDIUM, asks only residual questions during the six INTERVIEW states, and merge-writes the six output files at WRITE (CLAUDE.md is section-replaced by ATX heading, SPEC/SKILL files are rewritten only when template-only per CRLF-normalized SHA-256 match against `workflow-meta.json`, PROGRESS.md is append-only).
+- **`src/core/setup-state.js`** (PR #104) — persistence module for `.claude/cache/setup-state.json` (schemaVersion 1). Exports `loadSetupState`, `saveSetupState`, `clearSetupState`, `isSetupStateStale`, plus the `STATE_NAMES`, `QUESTION_IDS`, and `UNCHECKED_ROUTING` contract constants. Schema validation rejects unknown `currentState` values, `interviewAnswers` keys outside the QuestionId enumeration, mis-routed `<state>.unchecked.<field>` prefixes, and non-string answer values. `saveSetupState` preserves `startedAt` from an existing file across re-saves and refreshes `updatedAt` automatically.
+- **`worclaude setup-state` CLI subcommand** (PR #104) — four sub-subcommands: `show` (prints state JSON or `no state`), `save --stdin` (reads JSON from stdin, validates, persists — the ONLY mechanism `/setup` uses to write state), `reset` (idempotent delete), `resume-info` (pre-formatted `state: X, age: N unit(s), staleness: fresh|stale` line so Claude echoes rather than computes relative time). Exit codes: `0` success, `1` fatal, `2` invalid args.
+- **Anti-drift rules embedded in `setup.md`** (PR #104) — seven CRITICAL EXECUTION RULES pinned at the top of the command file. Sequential state advance only; no backward advance within an invocation; off-topic input triggers a restate, never an answer; `cancel setup` matches regex `/^(cancel|stop|abort)( setup)?[.!?\s]*$/i` and preserves state; tool use is whitelisted (scanner + `setup-state` CLI + two cache reads between SCAN and WRITE; the six target file reads/writes only at WRITE, plus `workflow-meta.json` for hash lookup); no memory pre-fill from prior sessions; prompts render verbatim in fenced code blocks, including state-machine control prose (resume preamble, back rejection, off-topic restate prefix, cancel acknowledgment).
+- **QuestionId enumeration** (PR #104) as the load-bearing `interviewAnswers` key contract (22 IDs across 6 INTERVIEW states) plus a `<state>.unchecked.<field>` prefix namespace for rejected high-confidence field re-asks, routed per a documented table (e.g., `scripts` rejected at CONFIRM_HIGH → re-asked in INTERVIEW_WORKFLOW under key `workflow.unchecked.scripts`).
+- **Field rendering table** reproduced in `setup.md` (PR #104) — the contract between detection report shapes and the human-readable value strings rendered at CONFIRM_HIGH and CONFIRM_MEDIUM. Mirrors `src/commands/scan.js:summarizeValue` semantics for all 14 detector fields plus the fallback scalar/array/object cases.
+
+### Changed
+
+- **`.gitignore` scaffolder** (PR #103) — `updateGitignore()` in `src/core/scaffolder.js` now writes `.claude/cache/` in addition to the existing seven entries. `cleanGitignore()` in `src/core/remover.js` removes the new entry on `worclaude delete`.
+- **`/setup` precondition** (PR #104) — `.claude/workflow-meta.json` must exist (canonical Worclaude init marker). Non-init'd projects get a clear "Run `worclaude init` first" message and exit, replacing the prior behavior of proceeding with undefined semantics.
+
+### Tests
+
+- **107 new scanner tests** (PR #103) across `tests/core/project-scanner/detectors/*.test.js` (14 files, 83 tests — positive, negative, and edge cases including multiple lockfiles, all four pyproject dep locations, quoted/prefixed env lines, monorepo with and without workspaces), `tests/core/project-scanner/index.test.js` (12 tests — happy path against six real fixtures, broken-detector and slow-detector handling via the `overrideDetectors` test seam, JSON round-trip), `tests/core/project-scanner/write-report.test.js` (7 tests), `tests/commands/scan.test.js` (5 tests — `--path`, `--json`, `--quiet`, cwd default, and exit-code-1 paths). 8 fixtures under `tests/fixtures/scanner/`: `nextjs-pnpm/`, `fastapi-poetry/`, `fastapi-pep621/`, `fastapi-pep735/`, `rust-cli/`, `monorepo-pnpm/`, `empty/`, `mixed-lockfiles/`.
+- **47 new setup-state tests** (PR #104) — `tests/core/setup-state.test.js` (24 unit tests covering load/save/clear/isStale happy paths, corrupt JSON, unsupported schemaVersion, unknown currentState, unknown interviewAnswers keys, mis-routed unchecked prefixes, startedAt preservation, updatedAt refresh, custom staleHours) and `tests/commands/setup-state.test.js` (23 CLI tests — four subcommands' happy and error paths, `save --stdin` round-trip with an in-process `inputStream` injection seam plus one end-to-end `spawnSync` smoke test, `resume-info` unit picking at minute/hour/day boundaries, invalid-arg exit 2). Total suite: **729/729 pass**.
+
+### Non-goals (explicitly deferred)
+
+- No `/setup --edit <field>` flow for correcting prior answers (Tier 2).
+- No automated state-machine test harness (mock-Claude driver walking every transition). Tier 2.
+- No automated end-to-end testing of `/setup` across fixture projects — manual e2e per the 13-case checklist in the phase prompt.
+- No schema migrator for `setup-state.json`. v1 policy is "reset on schema bump."
+- No architecture classification, directory-tree module inference, CI required-check detection (GitHub API), or monorepo sub-package scanning — all Tier 2.
+- No rename of the existing `src/core/detector.js` (scenario detection). The new scanner lives under `src/core/project-scanner/` to avoid name collision.
+
 ## [2.5.1] — 2026-04-21
 
 Patch release fixing a user-visible bug found while dogfooding the v2.5.0 upgrade: reference-copy template files (the copies worclaude writes when your customized file and the shipped template both change) were being placed as `.workflow-ref.md` siblings next to the live file — including inside `.claude/commands/`, where Claude Code's command loader discovered them as phantom slash commands like `/sync.workflow-ref`, and inside `.claude/agents/`, where they could shadow live agents. Reference copies now live in a dedicated `.claude/workflow-ref/` tree that Claude Code does not scan. Installs upgrading from pre-v2.5.1 have their legacy reference files automatically relocated on the next `worclaude upgrade`.

package/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.4.x   | :white_check_mark: |
-| < 2.4   | :x:                |
+| 2.6.x   | :white_check_mark: |
+| < 2.6   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -19,3 +19,50 @@ Please do **not** open a public issue for security vulnerabilities.
 
 You can expect an initial response within 48 hours.
 If the vulnerability is accepted, a fix will be prioritized and released as a patch version.
+
+## Supply Chain Scanner Findings
+
+Automated SCA tools (Socket, Snyk, GitHub Dependabot) sometimes surface
+alerts that are not real exposures for worclaude. The most common cases:
+
+### Test fixture manifests are not real dependencies
+
+`tests/fixtures/scanner/**` contains static `package.json`, `pnpm-lock.yaml`,
+`package-lock.json`, and `pyproject.toml` files used to exercise the
+project-scanner detectors in `src/core/project-scanner/`. They pin
+intentionally-outdated versions (e.g. `next@14.2.3`, `vitest@1.4.0`,
+`prisma@5.10.0`) so the detectors have realistic inputs to match against.
+
+These fixtures are:
+
+- **Never installed.** They are not referenced from the root `package.json`.
+- **Not shipped to npm.** `package.json`'s `files` whitelist publishes only
+  `src/`, `templates/`, and top-level docs. `tests/` is excluded.
+- **Not executed.** The scanner reads them as JSON/TOML and inspects the
+  dependency lists; it never imports or runs the packages named inside.
+
+Worclaude's repo includes `socket.yml` to stop Socket from scanning this
+directory. Other SCA tools may need an equivalent `ignore` directive.
+
+### Real runtime dependencies
+
+```
+chalk        ^5.4.1
+commander   ^13.1.0
+fs-extra    ^11.3.0
+inquirer    ^12.5.0
+ora          ^8.2.0
+smol-toml    ^1.6.1
+yaml         ^2.8.3
+```
+
+No Next.js, React, Express, Prisma, or Stripe appear at runtime despite
+what a fixture-inclusive scan might suggest.
+
+### Filesystem access flag is by design
+
+Worclaude scaffolds files into the user's project tree: templates → `.claude/`,
+settings.json merges, timestamped backups under `.claude-backup-*/`, and
+an opt-in `workflow-meta.json`. The `fs-extra`-based filesystem capability
+flag is a disclosure, not a vulnerability — removing it would delete the
+tool's core function.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
@@ -68,7 +68,9 @@
     "commander": "^13.1.0",
     "fs-extra": "^11.3.0",
     "inquirer": "^12.5.0",
-    "ora": "^8.2.0"
+    "ora": "^8.2.0",
+    "smol-toml": "^1.6.1",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "eslint": "^9.22.0",

package/src/commands/scan.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import { scanProject, writeDetectionReport } from '../core/project-scanner/index.js';
+import * as display from '../utils/display.js';
+
+function truncate(text, max) {
+  if (text.length <= max) return text;
+  return text.slice(0, max - 1) + '…';
+}
+
+function summarizeValue(result) {
+  const { value, field } = result;
+
+  switch (field) {
+    case 'readme':
+      return truncate(value.projectDescription || '(no description extracted)', 80);
+    case 'ci': {
+      const n = value.workflows?.length || 0;
+      return `${value.provider}, ${n} workflow${n === 1 ? '' : 's'}`;
+    }
+    case 'testing':
+      return value.framework + (value.configFile ? ` (${value.configFile})` : '');
+    case 'scripts': {
+      const parts = [];
+      for (const key of ['dev', 'test', 'build', 'lint']) {
+        if (value[key]) parts.push(`${key}=${value[key].key}`);
+      }
+      return parts.join(' ') || '(no standard scripts)';
+    }
+    case 'envVariables':
+      return `${value.names.length} variables`;
+    case 'orm':
+      return value.name;
+    case 'monorepo':
+      return `${value.tool} (${value.packagePaths.length} packages)`;
+    case 'specDocs':
+      return `${value.length} doc${value.length === 1 ? '' : 's'}`;
+    case 'frameworks':
+      return value.map((v) => (v.version ? `${v.name} ${v.version}` : v.name)).join(', ');
+    default:
+      if (typeof value === 'string') return value;
+      if (Array.isArray(value)) return value.join(', ');
+      return JSON.stringify(value);
+  }
+}
+
+function formatField(field) {
+  return field.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase());
+}
+
+function renderSummary(report, reportPath) {
+  const byConfidence = { high: [], medium: [], low: [] };
+  for (const r of report.results) {
+    byConfidence[r.confidence]?.push(r);
+  }
+
+  display.newline();
+  display.sectionHeader('WORCLAUDE SCAN');
+  display.dim(`Path: ${report.projectRoot}`);
+  display.newline();
+
+  for (const tier of ['high', 'medium', 'low']) {
+    const items = byConfidence[tier];
+    display.barLine(
+      display.white(`${tier[0].toUpperCase() + tier.slice(1)} confidence (${items.length})`)
+    );
+    if (items.length === 0) {
+      display.dim('(none)');
+    } else {
+      for (const item of items) {
+        const label = formatField(item.field).padEnd(20);
+        const summary = summarizeValue(item);
+        const source = item.source ? display.dimColor(`(${item.source})`) : '';
+        console.log(`  ${display.green('✓')} ${label} ${summary} ${source}`);
+      }
+    }
+    display.newline();
+  }
+
+  display.barLine(display.white(`Errors (${report.errors.length})`));
+  if (report.errors.length === 0) {
+    display.dim('(none)');
+  } else {
+    for (const err of report.errors) {
+      console.log(`  ${display.red('✗')} ${err.detector}: ${err.kind} — ${err.message}`);
+    }
+  }
+  display.newline();
+
+  display.success(
+    `Report written to ${path.relative(report.projectRoot, reportPath) || reportPath}`
+  );
+  display.newline();
+}
+
+export async function scanCommand(options = {}) {
+  const projectRoot = path.resolve(options.path || process.cwd());
+  const quiet = !!options.quiet;
+  const jsonMode = !!options.json;
+
+  let report;
+  try {
+    report = await scanProject(projectRoot);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let reportPath;
+  try {
+    reportPath = await writeDetectionReport(report, projectRoot);
+  } catch (err) {
+    console.error(`Error writing detection report: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (!quiet) {
+    renderSummary(report, reportPath);
+  }
+}

package/src/commands/setup-state.js

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import { text } from 'node:stream/consumers';
+import {
+  loadSetupState,
+  saveSetupState,
+  clearSetupState,
+  isSetupStateStale,
+} from '../core/setup-state.js';
+
+function formatAge(updatedAtIso) {
+  const ageMs = Date.now() - Date.parse(updatedAtIso);
+  const minutes = Math.floor(ageMs / (60 * 1000));
+  if (minutes < 90) {
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+  }
+  const hours = Math.floor(ageMs / (60 * 60 * 1000));
+  if (hours < 48) {
+    return `${hours} hour${hours === 1 ? '' : 's'}`;
+  }
+  const days = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+  return `${days} day${days === 1 ? '' : 's'}`;
+}
+
+async function runOrExit(fn, { errorPrefix = 'Error' } = {}) {
+  try {
+    await fn();
+  } catch (err) {
+    console.error(`${errorPrefix}: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function showSubcommand(projectRoot) {
+  await runOrExit(async () => {
+    const state = await loadSetupState(projectRoot);
+    if (state === null) {
+      console.log('no state');
+      return;
+    }
+    console.log(JSON.stringify(state, null, 2));
+  });
+}
+
+async function saveSubcommand(projectRoot, options) {
+  if (!options.stdin) {
+    console.error('Error: save requires --stdin');
+    process.exitCode = 2;
+    return;
+  }
+
+  const inputStream = options.inputStream || process.stdin;
+  let raw;
+  try {
+    raw = await text(inputStream);
+  } catch (err) {
+    console.error(`Error reading stdin: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`Error: invalid JSON on stdin: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await runOrExit(() => saveSetupState(projectRoot, parsed));
+}
+
+async function resetSubcommand(projectRoot) {
+  await runOrExit(() => clearSetupState(projectRoot));
+}
+
+async function resumeInfoSubcommand(projectRoot) {
+  await runOrExit(async () => {
+    const state = await loadSetupState(projectRoot);
+    if (state === null) {
+      console.log('no state');
+      return;
+    }
+    const age = formatAge(state.updatedAt);
+    const staleness = isSetupStateStale(state) ? 'stale' : 'fresh';
+    console.log(`state: ${state.currentState}, age: ${age}, staleness: ${staleness}`);
+  });
+}
+
+const SUBCOMMANDS = new Set(['show', 'save', 'reset', 'resume-info']);
+
+export async function setupStateCommand(subcommand, options = {}) {
+  if (!SUBCOMMANDS.has(subcommand)) {
+    console.error(
+      `Error: unknown subcommand: ${subcommand} (expected one of show, save, reset, resume-info)`
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const projectRoot = path.resolve(options.path || process.cwd());
+
+  switch (subcommand) {
+    case 'show':
+      return showSubcommand(projectRoot);
+    case 'save':
+      return saveSubcommand(projectRoot, options);
+    case 'reset':
+      return resetSubcommand(projectRoot);
+    case 'resume-info':
+      return resumeInfoSubcommand(projectRoot);
+  }
+}

package/src/core/project-scanner/detectors/ci.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileExists, dirExists } from '../../../utils/file.js';
+
+export default async function detectCi(projectRoot) {
+  const results = [];
+
+  const workflowsDir = path.join(projectRoot, '.github', 'workflows');
+  if (await dirExists(workflowsDir)) {
+    try {
+      const entries = await fs.readdir(workflowsDir, { withFileTypes: true });
+      const workflows = entries
+        .filter((e) => e.isFile() && /\.ya?ml$/.test(e.name))
+        .map((e) => e.name)
+        .sort();
+      if (workflows.length > 0) {
+        results.push({
+          field: 'ci',
+          value: { provider: 'GitHub Actions', workflows },
+          confidence: 'high',
+          source: '.github/workflows/',
+          candidates: null,
+        });
+      }
+    } catch {
+      /* missing or unreadable — non-fatal */
+    }
+  }
+
+  const other = [
+    { file: '.gitlab-ci.yml', provider: 'GitLab CI' },
+    { file: '.circleci/config.yml', provider: 'CircleCI' },
+    { file: 'azure-pipelines.yml', provider: 'Azure Pipelines' },
+    { file: 'Jenkinsfile', provider: 'Jenkins' },
+    { file: '.drone.yml', provider: 'Drone' },
+    { file: 'bitbucket-pipelines.yml', provider: 'Bitbucket Pipelines' },
+  ];
+  for (const { file, provider } of other) {
+    if (await fileExists(path.join(projectRoot, file))) {
+      results.push({
+        field: 'ci',
+        value: { provider, workflows: [path.basename(file)] },
+        confidence: 'high',
+        source: file,
+        candidates: null,
+      });
+    }
+  }
+
+  return results;
+}

package/src/core/project-scanner/detectors/deployment.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { fileExists } from '../../../utils/file.js';
+
+const DEPLOYMENTS = [
+  { file: 'vercel.json', target: 'Vercel' },
+  { file: 'netlify.toml', target: 'Netlify' },
+  { file: 'Dockerfile', target: 'Docker' },
+  { file: 'fly.toml', target: 'Fly.io' },
+  { file: 'railway.toml', target: 'Railway' },
+  { file: 'app.yaml', target: 'Google App Engine' },
+  { file: 'serverless.yml', target: 'Serverless Framework' },
+  { file: 'render.yaml', target: 'Render' },
+  { file: '.platform.app.yaml', target: 'Platform.sh' },
+  { file: 'wrangler.toml', target: 'Cloudflare Workers' },
+  { file: 'amplify.yml', target: 'AWS Amplify' },
+];
+
+export default async function detectDeployment(projectRoot) {
+  const results = [];
+  for (const { file, target } of DEPLOYMENTS) {
+    if (await fileExists(path.join(projectRoot, file))) {
+      results.push({
+        field: 'deployment',
+        value: target,
+        confidence: 'high',
+        source: file,
+        candidates: null,
+      });
+    }
+  }
+  return results;
+}

package/src/core/project-scanner/detectors/env-variables.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { fileExists, readFile } from '../../../utils/file.js';
+import { getAllDeps, depMatches } from '../manifests.js';
+
+const ENV_FILES = ['.env.example', '.env.template', '.env.sample'];
+
+const SDK_SERVICES = [
+  { sdkPrefix: '@stripe/', service: 'Stripe', envPrefix: 'STRIPE_' },
+  { sdkPrefix: 'stripe', service: 'Stripe', envPrefix: 'STRIPE_' },
+  { sdkPrefix: '@aws-sdk/', service: 'AWS', envPrefix: 'AWS_' },
+  { sdkPrefix: '@sendgrid/', service: 'SendGrid', envPrefix: 'SENDGRID_' },
+  { sdkPrefix: 'twilio', service: 'Twilio', envPrefix: 'TWILIO_' },
+  { sdkPrefix: 'openai', service: 'OpenAI', envPrefix: 'OPENAI_' },
+  { sdkPrefix: '@anthropic-ai/', service: 'Anthropic', envPrefix: 'ANTHROPIC_' },
+  { sdkPrefix: '@google-cloud/', service: 'Google Cloud', envPrefix: 'GOOGLE_' },
+  { sdkPrefix: '@slack/', service: 'Slack', envPrefix: 'SLACK_' },
+  { sdkPrefix: 'postmark', service: 'Postmark', envPrefix: 'POSTMARK_' },
+  { sdkPrefix: 'resend', service: 'Resend', envPrefix: 'RESEND_' },
+  { sdkPrefix: '@sentry/', service: 'Sentry', envPrefix: 'SENTRY_' },
+];
+
+function parseEnvNames(content) {
+  const names = [];
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Z_][A-Z0-9_]*)\s*=/);
+    if (match) names.push(match[1]);
+  }
+  return names;
+}
+
+export default async function detectEnvVariables(projectRoot) {
+  let sourceFile = null;
+  let content = null;
+  for (const f of ENV_FILES) {
+    const p = path.join(projectRoot, f);
+    if (await fileExists(p)) {
+      sourceFile = f;
+      content = await readFile(p);
+      break;
+    }
+  }
+  if (!sourceFile) return [];
+
+  const names = parseEnvNames(content);
+  if (names.length === 0) {
+    return [
+      {
+        field: 'envVariables',
+        value: { names: [], inferredServices: [] },
+        confidence: 'high',
+        source: sourceFile,
+        candidates: null,
+      },
+    ];
+  }
+
+  const { js, py } = await getAllDeps(projectRoot);
+  const allDeps = { ...js, ...py };
+  const inferredServices = new Set();
+  for (const { sdkPrefix, service, envPrefix } of SDK_SERVICES) {
+    const pattern = sdkPrefix.endsWith('/') ? `${sdkPrefix}*` : sdkPrefix;
+    if (depMatches(allDeps, pattern) && names.some((n) => n.startsWith(envPrefix))) {
+      inferredServices.add(service);
+    }
+  }
+
+  return [
+    {
+      field: 'envVariables',
+      value: { names, inferredServices: Array.from(inferredServices) },
+      confidence: 'high',
+      source: sourceFile,
+      candidates: null,
+    },
+  ];
+}

package/src/core/project-scanner/detectors/external-apis.js

@@ -0,0 +1,45 @@
+import { getAllDeps, depMatches } from '../manifests.js';
+
+const SDK_MAP = [
+  { match: 'stripe', service: 'Stripe' },
+  { match: '@sendgrid/', service: 'SendGrid' },
+  { match: '@aws-sdk/', service: 'AWS' },
+  { match: 'twilio', service: 'Twilio' },
+  { match: 'openai', service: 'OpenAI' },
+  { match: '@anthropic-ai/sdk', service: 'Anthropic' },
+  { match: '@google-cloud/', service: 'Google Cloud' },
+  { match: '@slack/', service: 'Slack' },
+  { match: 'postmark', service: 'Postmark' },
+  { match: 'resend', service: 'Resend' },
+  { match: 'algoliasearch', service: 'Algolia' },
+  { match: 'pusher', service: 'Pusher' },
+  { match: 'posthog-js', service: 'PostHog' },
+  { match: 'posthog-node', service: 'PostHog' },
+  { match: '@sentry/', service: 'Sentry' },
+  { match: 'mixpanel', service: 'Mixpanel' },
+  { match: 'mixpanel-browser', service: 'Mixpanel' },
+];
+
+export default async function detectExternalApis(projectRoot) {
+  const { js, py, hasPackageJson, hasPyproject } = await getAllDeps(projectRoot);
+  if (!hasPackageJson && !hasPyproject) return [];
+
+  const allDeps = { ...js, ...py };
+  const services = new Set();
+  for (const { match, service } of SDK_MAP) {
+    const pattern = match.endsWith('/') ? `${match}*` : match;
+    if (depMatches(allDeps, pattern)) services.add(service);
+  }
+
+  if (services.size === 0) return [];
+
+  return [
+    {
+      field: 'externalApis',
+      value: Array.from(services),
+      confidence: 'high',
+      source: hasPackageJson ? 'package.json' : 'pyproject.toml',
+      candidates: null,
+    },
+  ];
+}

package/src/core/project-scanner/detectors/frameworks.js

@@ -0,0 +1,56 @@
+import { getAllDeps } from '../manifests.js';
+
+const FRAMEWORKS = [
+  { dep: 'next', name: 'Next.js' },
+  { dep: 'nuxt', name: 'Nuxt' },
+  { dep: 'astro', name: 'Astro' },
+  { dep: 'remix', name: 'Remix' },
+  { dep: 'sveltekit', name: 'SvelteKit' },
+  { dep: '@sveltejs/kit', name: 'SvelteKit' },
+  { dep: 'react', name: 'React' },
+  { dep: 'vue', name: 'Vue' },
+  { dep: 'svelte', name: 'Svelte' },
+  { dep: 'solid-js', name: 'SolidJS' },
+  { dep: 'express', name: 'Express' },
+  { dep: 'fastify', name: 'Fastify' },
+  { dep: 'hono', name: 'Hono' },
+  { dep: 'koa', name: 'Koa' },
+  { dep: '@nestjs/core', name: 'NestJS' },
+  { dep: 'fastapi', name: 'FastAPI' },
+  { dep: 'starlette', name: 'Starlette' },
+  { dep: 'django', name: 'Django' },
+  { dep: 'flask', name: 'Flask' },
+];
+
+export default async function detectFrameworks(projectRoot) {
+  const { js, py, hasPackageJson, hasPyproject } = await getAllDeps(projectRoot);
+  if (!hasPackageJson && !hasPyproject) return [];
+
+  const detected = [];
+  const sources = new Set();
+  const seen = new Set();
+  for (const { dep, name } of FRAMEWORKS) {
+    if (seen.has(name)) continue;
+    if (js[dep] !== undefined) {
+      detected.push({ name, version: typeof js[dep] === 'string' ? js[dep] : '' });
+      sources.add('package.json');
+      seen.add(name);
+    } else if (py[dep] !== undefined) {
+      detected.push({ name, version: typeof py[dep] === 'string' ? py[dep] : '' });
+      sources.add('pyproject.toml');
+      seen.add(name);
+    }
+  }
+
+  if (detected.length === 0) return [];
+
+  return [
+    {
+      field: 'frameworks',
+      value: detected,
+      confidence: 'high',
+      source: Array.from(sources).join(', '),
+      candidates: null,
+    },
+  ];
+}