@rawsql-ts/ztd-cli 0.17.0 → 0.20.0

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@rawsql-ts/ztd-cli",
-  "version": "0.17.0",
+  "version": "0.20.0",
   "description": "DB-agnostic scaffolding and DDL helpers for Zero Table Dependency projects",
   "main": "dist/index.js",
   "bin": {
     "ztd": "dist/index.js"
   },
+  "scripts": {
+    "prepack": "node -e \"const fs=require('fs');const cp=require('child_process');const npm=process.platform==='win32'?'npm.cmd':'npm';if(!fs.existsSync('dist/index.js')){process.exit(cp.spawnSync(npm,['run','build'],{stdio:'inherit'}).status??1)}\"",
+    "build": "pnpm --filter rawsql-ts run build && pnpm --filter @rawsql-ts/sql-grep-core run build && pnpm --filter @rawsql-ts/test-evidence-core run build && pnpm --filter @rawsql-ts/test-evidence-renderer-md run build && pnpm --filter @rawsql-ts/testkit-core run build && tsc -p tsconfig.json",
+    "test": "pnpm --filter @rawsql-ts/adapter-node-pg run build && vitest run --config vitest.config.ts",
+    "lint": "eslint src --ext .ts",
+    "release": "npm run lint && npm run test && npm run build && node -e \"require('fs').mkdirSync('../../tmp', { recursive: true })\" && pnpm pack --out ../../tmp/rawsql-ts-ztd-cli.tgz && pnpm publish --access public",
+    "test:consumer-validation": "vitest run --config vitest.config.ts tests/testEvidence.unit.test.ts tests/testEvidence.cli.test.ts tests/sqlCatalog.evidence.test.ts tests/testCaseCatalog.evidence.test.ts"
+  },
   "keywords": [
     "rawsql-ts",
     "ztd",
@@ -15,6 +23,11 @@
   ],
   "author": "msugiura",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mk3008/rawsql-ts.git",
+    "directory": "packages/ztd-cli"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -22,14 +35,18 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@rawsql-ts/test-evidence-core": "workspace:*",
+    "@rawsql-ts/test-evidence-renderer-md": "workspace:*",
     "chokidar": "^5.0.0",
     "commander": "^12.0.0",
     "diff": "^8.0.3",
     "fast-glob": "^3.3.3",
-    "rawsql-ts": "^0.16.0"
+    "rawsql-ts": "workspace:^",
+    "yaml": "^2.8.2",
+    "@rawsql-ts/sql-grep-core": "workspace:*"
   },
   "peerDependencies": {
-    "@rawsql-ts/adapter-node-pg": "^0.15.2"
+    "@rawsql-ts/adapter-node-pg": "workspace:^"
   },
   "peerDependenciesMeta": {
     "@rawsql-ts/adapter-node-pg": {
@@ -37,27 +54,21 @@
     }
   },
   "devDependencies": {
+    "@rawsql-ts/adapter-node-pg": "workspace:^",
+    "@rawsql-ts/testkit-core": "workspace:^",
+    "@rawsql-ts/testkit-postgres": "workspace:^",
     "@testcontainers/postgresql": "^10.28.0",
     "@types/diff": "^5.0.1",
     "@types/node": "^22.13.10",
     "pg": "^8.11.1",
     "testcontainers": "^10.28.0",
     "typescript": "^5.8.2",
-    "vitest": "^4.0.7",
-    "@rawsql-ts/adapter-node-pg": "^0.15.2",
-    "@rawsql-ts/testkit-core": "^0.15.1",
-    "@rawsql-ts/testkit-postgres": "^0.15.1"
+    "vitest": "^4.0.7"
   },
   "files": [
     "dist",
     "templates",
     "AGENTS.md",
     "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "lint": "eslint src --ext .ts",
-    "release": "npm run lint && npm run test && npm run build && npm pack --dry-run && npm publish --access public"
-  }
-}
+  ]
+}

package/templates/.editorconfig

@@ -1,16 +1,16 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_style = space
-indent_size = 2
-tab_width = 2
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false
-
-[*.sql]
-indent_size = 2
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+tab_width = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.sql]
+indent_size = 2

package/templates/.prettierignore

@@ -1,2 +1,2 @@
-tests/generated/**
-
+tests/generated/**
+

package/templates/.prettierrc

@@ -1,24 +1,24 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "all",
-  "tabWidth": 2,
-  "printWidth": 100,
-  "bracketSpacing": true,
-  "arrowParens": "always",
-  "plugins": ["prettier-plugin-sql"],
-  "overrides": [
-    {
-      "files": "*.sql",
-      "options": {
-        "parser": "sql"
-      }
-    },
-    {
-      "files": "*.md",
-      "options": {
-        "parser": "markdown"
-      }
-    }
-  ]
-}
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "plugins": ["prettier-plugin-sql"],
+  "overrides": [
+    {
+      "files": "*.sql",
+      "options": {
+        "parser": "sql"
+      }
+    },
+    {
+      "files": "*.md",
+      "options": {
+        "parser": "markdown"
+      }
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -1,52 +1,30 @@
-# Workspace AGENTS
-
-This repository uses directory-scoped AGENTS.
-Rules live close to where the work happens.
-
-## Rule precedence
-
-- The closest "AGENTS.md" to the file being edited has the highest priority.
-- Parent directories provide shared rules.
-- Child directories should only describe deltas.
-
-## Global non-negotiables
-
-- Do not guess. If something is unknown, state "Not observed" and propose the next check.
-- Do not edit generated artifacts unless explicitly instructed.
-- Respect ownership boundaries: human-owned contracts must not be changed without explicit instruction.
-
-## Runtime vs non-runtime
-
-- Runtime assets live under "src/": executed/loaded by the application.
-- Non-runtime assets live under "ztd/" and parts of "tests/": used for verification and generation.
-
-## Human-owned vs AI-assisted (important)
-
-Human-owned (do not change without explicit instruction):
-- "ztd/ddl" (physical schema / DDL)
-- "src/catalog/specs" (query contracts: params + DTO + semantics)
-- "src/sql" (SQL assets; AI may propose patches, but do not rewrite intent)
-
-AI-assisted (implementation and verification):
-- "src/repositories"
-- "src/catalog/runtime"
-- "tests" (except "tests/generated")
-
-Never touch by hand:
-- "tests/generated"
-
-## Where to read next
-
-- "src/catalog/AGENTS.md": catalog layout and contract boundaries
-- "src/repositories/AGENTS.md": repository responsibilities and restrictions
-- "src/sql/AGENTS.md": SQL asset rules
-- "tests/AGENTS.md": ZTD testing rules
-- "ztd/ddl/AGENTS.md": DDL authoring rules
-
-## Test environment guarantee (important)
-
-- This workspace MUST be test-runnable immediately after initialization.
-- `pnpm test` (or equivalent) must not fail due to missing configuration.
-- Test runner configuration (e.g. vitest.config.ts) is considered part of the template contract.
-
-If tests fail due to missing config, this is a template defect, not a user error.
+# Package Scope
+- Applies to `packages/ztd-cli/templates`.
+- Defines repository-wide guardrails for generated project templates.
+- Provides parent rules for runtime (`src`), tests (`tests`), and metadata (`ztd`) without forcing one application style on every subtree.
+
+# Policy
+## REQUIRED
+- The nearest nested `AGENTS.md` MUST be treated as highest-priority policy for edited files.
+- Unknown facts during template work MUST be reported as `Not observed` with the next check.
+- Generated artifacts MUST remain unedited unless explicit instruction exists.
+- Preserve layer boundaries: transport, application, domain, and infrastructure concerns MUST remain explicit when those directories exist.
+- Human-owned contract directories (`ztd/ddl`, `src/catalog/specs`, `src/sql`) MUST NOT be semantically changed without explicit instruction.
+- Template output MUST include runnable test configuration at initialization.
+
+## ALLOWED
+- AI-assisted implementation MAY occur in infrastructure adapters, catalog runtime, and tests excluding `tests/generated`.
+
+## PROHIBITED
+- Manual edits under `tests/generated`.
+- Treating ZTD-specific workflow rules as repository-global rules.
+
+# Mandatory Workflow
+- Template changes MUST preserve an executable `pnpm test` path for initialized projects.
+
+# Hygiene
+- Keep directory-local deltas in child `AGENTS.md`; avoid restating parent rules in child files.
+
+# References
+- Rationale: [DESIGN.md](./DESIGN.md)
+- Operational notes: [DEV_NOTES.md](./DEV_NOTES.md)

package/templates/CONTEXT.md

@@ -0,0 +1,11 @@
+# Agent Context
+
+- Prefer `ztd --output json` in automation.
+- Treat this file as a high-level index only; rely on subtree `AGENTS.md` files for path-specific rules.
+- Prefer `ztd model-gen --probe-mode ztd` during the inner loop when local DDL is the source of truth.
+- Use `--dry-run` before file-writing commands when you need a safe validation pass.
+- Keep `ztd/ddl` as the human-owned schema source of truth.
+- Regenerate `tests/generated/*` with `ztd ztd-config`; do not edit generated files manually.
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`; it does not read `DATABASE_URL` automatically.
+- Treat `ddl pull` and `ddl diff` as explicit target inspection commands. Pass `--url` or a complete `--db-*` flag set when using them.
+- Keep transport, application, and domain work free from direct ZTD assumptions unless you are editing persistence infrastructure.

package/templates/CONTEXT.webapi.md

@@ -0,0 +1,11 @@
+# Agent Context
+
+- Treat this file as a top-level index for the layered WebAPI layout.
+- Keep `src/domain`, `src/application`, and `src/presentation/http` free from direct ZTD assumptions.
+- Apply ZTD-specific workflow rules only inside `src/infrastructure/persistence`, `src/sql`, `src/catalog`, and `ztd`.
+- Prefer `ztd model-gen --probe-mode ztd` during the inner loop when local DDL is the source of truth.
+- Use `--dry-run` before file-writing commands when you need a safe validation pass.
+- Keep `ztd/ddl` as the human-owned schema source of truth.
+- Regenerate `tests/generated/*` with `ztd ztd-config`; do not edit generated files manually.
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`; runtime settings such as `DATABASE_URL` remain outside its ownership.
+- Treat `ddl pull` and `ddl diff` as explicit target inspection commands. Pass `--url` or a complete `--db-*` flag set when using them.

package/templates/DESIGN.md

@@ -0,0 +1,17 @@
+# ZTD Template Design Notes
+
+## Role and Boundaries
+- Defines template-level design intent for ownership and runtime/test split.
+- Clarifies where human-owned contracts stop and implementation wiring begins.
+
+## Non-Goals
+- Replacing directory-local AGENTS contracts.
+- Embedding operational command playbooks.
+
+## Ownership Model
+- Human-owned directories preserve domain contracts and SQL intent.
+- AI-assisted directories implement runtime wiring and verification logic.
+
+## Runtime Split
+- `src/` contains runtime assets.
+- `tests/` and `ztd/` contain verification and generation inputs.

package/templates/DEV_NOTES.md

@@ -0,0 +1,14 @@
+# ZTD Template Dev Notes
+
+## Commands
+- `pnpm test` in initialized template projects.
+
+## Troubleshooting
+- Template initialization must include runnable test configuration and at least one executable test.
+
+## Navigation
+- `src/catalog/AGENTS.md`
+- `src/repositories/AGENTS.md`
+- `src/sql/AGENTS.md`
+- `tests/AGENTS.md`
+- `ztd/ddl/AGENTS.md`

package/templates/PROMPT_DOGFOOD.webapi.md

@@ -0,0 +1,49 @@
+# Prompt Dogfooding
+
+Use this checklist when you want to confirm that generic WebAPI requests stay focused on transport, application, and domain layers unless persistence work is explicitly requested.
+
+## Prompt 1
+
+Prompt:
+
+```text
+Convert to WebAPI
+```
+
+Expected focus:
+- `src/presentation/http`
+- `src/application`
+- `src/domain`
+
+Expected non-focus:
+- `src/sql`
+- `src/catalog`
+- `ztd/ddl`
+- `src/infrastructure/persistence`
+- `src/infrastructure/telemetry`
+
+## Prompt 2
+
+Prompt:
+
+```text
+Add SQL and implement repository
+```
+
+Expected focus:
+- `src/infrastructure/persistence/repositories`
+- `src/sql`
+- `src/catalog/specs`
+- `src/catalog/runtime`
+- `ztd/ddl`
+
+Expected non-focus:
+- unrelated HTTP transport rewrites
+- domain-wide refactors that are not required by the repository change
+
+## Record Template
+
+| Prompt | Primary files mentioned | Unwanted ZTD leakage? | Notes |
+| --- | --- | --- | --- |
+| `Convert to WebAPI` | | | |
+| `Add SQL and implement repository` | | | |

package/templates/README.md

@@ -1,14 +1,46 @@
-# Zero Table Dependency Project
-
-This project uses Zero Table Dependency (ZTD) to keep SQL, DDL, and tests aligned.
-
-Key folders:
-- ztd/ddl: schema files (source of truth)
-- src: application SQL and repositories
-- tests: ZTD tests and support
-
-Next steps:
-1. Update `ztd/ddl/<schema>.sql` if needed.
-2. Run `npx ztd ztd-config`.
-3. Provide a SqlClient implementation.
-4. Run tests (`pnpm test` or `npx vitest run`).
+# Zero Table Dependency Project
+
+This project uses Zero Table Dependency (ZTD) to keep SQL, DDL, and tests aligned.
+
+Conceptual model:
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`.
+- `DATABASE_URL` and other runtime or deployment database settings are outside the ownership of `ztd-cli`.
+- Any non-ZTD database target must be passed explicitly via `--url` or `--db-*`.
+- `ztd-cli` may generate migration SQL artifacts, but it does not apply them.
+
+Quick boundary table:
+- `ZTD_TEST_DATABASE_URL`: owned by `ztd-cli` for ZTD tests and verification
+- `DATABASE_URL`: runtime or deployment concern, not read automatically by `ztd-cli`
+- `--url` / complete `--db-*`: explicit target inspection only
+
+Key folders:
+- ztd/ddl: schema files (source of truth)
+- src: application SQL and repositories
+- tests: ZTD tests and support
+
+Next steps:
+1. Update `ztd/ddl/<schema>.sql` if needed.
+2. Run `pnpm exec ztd ztd-config` (or `npx ztd ztd-config` if you prefer npm-style invocation).
+3. Run `pnpm exec ztd model-gen --probe-mode ztd <sql-file> --out <spec-file>` when you want a QuerySpec scaffold from the local DDL snapshot.
+4. Wire repositories to `src/infrastructure/telemetry/repositoryTelemetry.ts` so application code can replace the default telemetry hook.
+5. Provide a SqlClient implementation.
+6. Run tests (`pnpm test` or `npx vitest run`).
+7. Use `ZTD_TEST_DATABASE_URL` for ZTD-owned test and verification workflows.
+8. Use `ztd model-gen --probe-mode live`, `ztd ddl pull`, or `ztd ddl diff` only for explicit target inspection by passing `--url` or a complete `--db-*` flag set.
+9. If you generate migration SQL artifacts, apply them with your deployment tooling instead of `ztd-cli`.
+
+If this project was scaffolded with `ztd init --local-source-root <monorepo-root>`, first run `pnpm install` (or `pnpm install --ignore-workspace` when nested under another `pnpm-workspace.yaml`), then `pnpm typecheck`, then `pnpm test`, then `pnpm ztd ztd-config`. The scaffold keeps `@rawsql-ts/sql-contract` as a normal package import even in local-source developer mode.
+
+For schema-change impact checks, `npx ztd query uses` defaults to the `impact` view. Table add / column add checks usually work with the default scan, while table rename / column rename / column type change checks often benefit from `--exclude-generated` so review-only specs under `src/catalog/specs/generated` do not add noise. The flag is optional and does not change the default scan set.
+
+If you later switch this scaffold into a layered WebAPI shape, add a prompt-dogfooding guide similar to `PROMPT_DOGFOOD.md` so generic transport requests can be checked for accidental ZTD leakage.
+
+Examples:
+
+```bash
+pnpm exec ztd query uses table public.sale_items --exclude-generated
+pnpm exec ztd query uses table public.sale_lines --exclude-generated
+pnpm exec ztd query uses column public.products.title --exclude-generated
+pnpm exec ztd query uses column public.sale_items.quantity --exclude-generated
+pnpm exec ztd query uses table public.sale_lines --view detail --exclude-generated
+```

package/templates/README.webapi.md

@@ -0,0 +1,38 @@
+# Zero Table Dependency WebAPI Project
+
+This scaffold separates WebAPI concerns into explicit layers so transport and use-case work do not accidentally inherit persistence-specific rules.
+
+Conceptual model:
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`.
+- Projects often also have a runtime or deployment database setting such as `DATABASE_URL`, but `ztd-cli` does not read it automatically.
+- Any non-ZTD database target must be passed explicitly via `--url` or `--db-*`.
+- `ztd-cli` may generate migration SQL artifacts, but it does not apply them.
+
+Quick boundary table:
+- `ZTD_TEST_DATABASE_URL`: owned by `ztd-cli` for ZTD tests and verification
+- `DATABASE_URL`: runtime or deployment concern, not read automatically by `ztd-cli`
+- `--url` / complete `--db-*`: explicit target inspection only
+
+Key folders:
+- `src/domain`: domain types and business rules with no direct ZTD dependency
+- `src/application`: use cases and orchestration over domain-facing ports
+- `src/presentation/http`: HTTP handlers, request parsing, and response shaping
+- `src/infrastructure/persistence`: repositories, SQL assets, and QuerySpec wiring
+- `src/sql`, `src/catalog`, `ztd/ddl`: ZTD-owned persistence assets
+- `tests`: smoke tests and test support
+
+Prompt dogfooding:
+- See `PROMPT_DOGFOOD.md` when you want to verify that generic WebAPI requests stay out of persistence-specific ZTD guidance unless repository or SQL work is explicitly requested.
+
+Next steps:
+1. Update `ztd/ddl/<schema>.sql` if needed.
+2. Run `pnpm exec ztd ztd-config` (or `npx ztd ztd-config` if you prefer npm-style invocation).
+3. Keep `src/domain`, `src/application`, and `src/presentation/http` free from direct SQL or DDL concerns.
+4. Use `pnpm exec ztd model-gen --probe-mode ztd <sql-file> --out <spec-file>` when you want a QuerySpec scaffold from the local DDL snapshot.
+5. Wire repositories to `src/infrastructure/telemetry/repositoryTelemetry.ts` only when you add SQL-backed repository classes.
+6. Provide a SqlClient implementation in `src/infrastructure/db`.
+7. Run tests (`pnpm test` or `npx vitest run`) with `ZTD_TEST_DATABASE_URL` when SQL-backed verification needs a managed test database.
+8. Treat `ddl pull` and `ddl diff` as explicit target inspection commands that require `--url` or a complete `--db-*` flag set.
+9. If you generate migration SQL artifacts, apply them outside `ztd-cli`.
+
+If this project was scaffolded with `ztd init --local-source-root <monorepo-root>`, first run `pnpm install` (or `pnpm install --ignore-workspace` when nested under another `pnpm-workspace.yaml`), then `pnpm typecheck`, then `pnpm test`, then `pnpm ztd ztd-config`. The scaffold keeps `@rawsql-ts/sql-contract` as a normal package import even in local-source developer mode.

package/templates/scripts/local-source-guard.mjs

@@ -0,0 +1,189 @@
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const projectRoot = process.cwd();
+const command = process.argv[2];
+
+if (command !== 'test' && command !== 'typecheck' && command !== 'ztd') {
+  console.error('local-source guard expects "test", "typecheck", or "ztd".');
+  process.exit(1);
+}
+
+if (command === 'ztd') {
+  const cliEntry = path.resolve(projectRoot, '__LOCAL_SOURCE_ZTD_CLI__');
+  const requestedSubcommand = process.argv.slice(3).join(' ').trim() || '(none)';
+  if (!existsSync(cliEntry)) {
+    console.error(
+      [
+        '[local-source guard] ztd cannot run against the local source checkout yet.',
+        '',
+        `What happened:`,
+        `- Requested subcommand: ${requestedSubcommand}`,
+        `- Project root: ${normalizePath(projectRoot)}`,
+        `- The local CLI entry was not found at ${normalizePath(cliEntry)}.`,
+        '',
+        'Next steps:',
+        '1. Build the local CLI package (for example: pnpm --filter @rawsql-ts/ztd-cli build)',
+        '2. Confirm this scaffold still points at the intended rawsql-ts monorepo root',
+        '3. Re-run pnpm ztd <subcommand>'
+      ].join('\n')
+    );
+    process.exit(1);
+  }
+
+  const cliArgs = process.argv.slice(3);
+  const result = spawnSync(process.execPath, [cliEntry, ...cliArgs], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    shell: false
+  });
+
+  // Surface execution failures explicitly so local-source dogfooding does not
+  // collapse permission, spawn, and signal problems into the same exit code.
+  if (result.error) {
+    console.error('[local-source guard] Failed to launch the local ztd CLI entry.');
+    console.error(`- Message: ${result.error.message}`);
+    if (result.error.stack) {
+      console.error(result.error.stack);
+    }
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    console.error('[local-source guard] The local ztd CLI entry was terminated by signal.');
+    console.error(`- Signal: ${result.signal}`);
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+const workspaceRoot = findAncestorPnpmWorkspaceRoot(projectRoot);
+const installCommand = workspaceRoot ? 'pnpm install --ignore-workspace' : 'pnpm install';
+const rerunCommand = command === 'test' ? 'pnpm test' : 'pnpm typecheck';
+const fallbackCommand = command === 'test' ? 'npx vitest run' : 'npx tsc --noEmit';
+const binaryName = process.platform === 'win32'
+  ? command === 'test'
+    ? 'vitest.cmd'
+    : 'tsc.cmd'
+  : command === 'test'
+  ? 'vitest'
+  : 'tsc';
+const binaryArgs = command === 'test' ? ['run'] : ['--noEmit'];
+const binaryPath = path.join(projectRoot, 'node_modules', '.bin', binaryName);
+const packageChecks = command === 'test'
+  ? ['vitest/package.json', 'zod/package.json', '@rawsql-ts/sql-contract/package.json']
+  : ['typescript/package.json', 'zod/package.json', '@rawsql-ts/sql-contract/package.json'];
+
+const resolutionIssues = inspectResolution(packageChecks);
+if (!existsSync(binaryPath) || resolutionIssues.length > 0) {
+  printGuidance({
+    command,
+    installCommand,
+    rerunCommand,
+    fallbackCommand,
+    workspaceRoot,
+    binaryPath,
+    resolutionIssues
+  });
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, binaryArgs, {
+  cwd: projectRoot,
+  stdio: 'inherit',
+  shell: process.platform === 'win32'
+});
+process.exit(result.status ?? 1);
+
+function inspectResolution(specifiers) {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+  const issues = [];
+
+  for (const specifier of specifiers) {
+    try {
+      const resolvedPath = specifier.endsWith('/package.json')
+        ? resolveInstalledPackageManifest(specifier)
+        : projectRequire.resolve(specifier);
+      if (!isInsideProject(resolvedPath)) {
+        issues.push(`${specifier} resolved outside this scaffold: ${normalizePath(resolvedPath)}`);
+      }
+    } catch {
+      issues.push(`${specifier} is not installed in this scaffold`);
+    }
+  }
+
+  return issues;
+}
+
+function resolveInstalledPackageManifest(specifier) {
+  const manifestRelativePath = path.join('node_modules', ...specifier.split('/'));
+  const manifestPath = path.join(projectRoot, manifestRelativePath);
+  if (!existsSync(manifestPath)) {
+    throw new Error(`${specifier} manifest is missing`);
+  }
+  return manifestPath;
+}
+
+function isInsideProject(filePath) {
+  const relativePath = path.relative(projectRoot, filePath);
+  return relativePath.length === 0 || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+function findAncestorPnpmWorkspaceRoot(rootDir) {
+  let cursor = path.resolve(rootDir);
+  while (true) {
+    const parentDir = path.dirname(cursor);
+    if (parentDir === cursor) {
+      return null;
+    }
+    cursor = parentDir;
+    if (existsSync(path.join(cursor, 'pnpm-workspace.yaml'))) {
+      return cursor;
+    }
+  }
+}
+
+function printGuidance({
+  command,
+  installCommand,
+  rerunCommand,
+  fallbackCommand,
+  workspaceRoot,
+  binaryPath,
+  resolutionIssues
+}) {
+  const commandLabel = command === 'test' ? 'pnpm test' : 'pnpm typecheck';
+  const lines = [
+    `[local-source guard] ${commandLabel} cannot run against this scaffold yet.`,
+    '',
+    'What happened:',
+    `- The local binary was not found at ${normalizePath(binaryPath)} or required packages resolved outside this project.`,
+  ];
+
+  if (workspaceRoot) {
+    lines.push(`- This project sits under pnpm workspace ${normalizePath(workspaceRoot)}, so pnpm may still be using the parent workspace context.`);
+  }
+
+  if (resolutionIssues.length > 0) {
+    lines.push('- Resolution details:');
+    for (const issue of resolutionIssues) {
+      lines.push(`  - ${issue}`);
+    }
+  }
+
+  lines.push(
+    '',
+    'Next steps:',
+    `1. Run ${installCommand}`,
+    `2. Re-run ${rerunCommand}`,
+    `3. If pnpm still looks absorbed by the parent workspace, try ${fallbackCommand}`
+  );
+  console.error(lines.join('\n'));
+}