@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/init/scaffolders/opencode-plugin/index.d.ts

@@ -0,0 +1,9 @@
+import { type MergeOptions, type MergeResult } from '#cli/commands/init/merge';
+export declare const OPENCODE_PLUGIN_RELATIVE_PATH = ".opencode/plugins/webpresso-dev-link.js";
+export interface ScaffoldOpencodePluginInput {
+    repoRoot: string;
+    options: MergeOptions;
+}
+export declare const OPENCODE_PLUGIN_CONTENT = "// Generated by webpresso (`wp setup`).\n//\n// Cross-runtime dev-link breakage warning for opencode. Mirrors the\n// SessionStart hook installed for Claude Code and Codex by shelling out\n// to the same `wp-check-dev-link` bin shipped with webpresso.\n//\n// The plugin emits the warning via stderr (visible in the opencode TUI)\n// on session.created, and pushes the same message into output.context\n// during compaction so it survives compacted sessions.\n//\n// Re-run `wp setup` to update this file. Delete it to opt out.\n\nconst HOOK_BIN = './node_modules/.bin/wp-check-dev-link'\n\nasync function detectBreakage($, directory) {\n  const result = await $`bun ${HOOK_BIN}`.cwd(directory).quiet().nothrow()\n  if (result.exitCode !== 0) return null\n  const stdout = result.stdout.toString().trim()\n  if (stdout === '') return null\n  try {\n    const envelope = JSON.parse(stdout)\n    return envelope?.hookSpecificOutput?.additionalContext ?? null\n  } catch {\n    return null\n  }\n}\n\nexport const WebpressoDevLinkPlugin = async ({ $, directory }) => {\n  const reportIfBroken = async () => {\n    const message = await detectBreakage($, directory)\n    if (message !== null) process.stderr.write(`\\n[opencode] ${message}\\n\\n`)\n    return message\n  }\n\n  await reportIfBroken()\n\n  return {\n    event: async ({ event }) => {\n      if (event?.type === 'session.created') await reportIfBroken()\n    },\n    'experimental.session.compacting': async (_input, output) => {\n      const message = await reportIfBroken()\n      if (message !== null && output && Array.isArray(output.context)) {\n        output.context.push(message)\n      }\n    },\n  }\n}\n";
+export declare function scaffoldOpencodePlugin(input: ScaffoldOpencodePluginInput): MergeResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/opencode-plugin/index.js

@@ -0,0 +1,86 @@
+/**
+ * `opencode-plugin` scaffolder — installs the dev-link warning plugin into
+ * `<repoRoot>/.opencode/plugins/webpresso-dev-link.js`.
+ *
+ * Why a plugin: opencode is the third runtime alongside Claude Code and
+ * Codex CLI. Per opencode docs (opencode.ai/docs/plugins) it loads
+ * JavaScript/TypeScript files from `.opencode/plugins/` automatically at
+ * startup. There is no shell-hook surface — opencode is a plugin-based
+ * extensibility model (event handlers, tool wrappers, compaction hooks).
+ *
+ * What this plugin does: shells out to `wp-check-dev-link` (the same bin
+ * Claude Code and Codex run as a SessionStart hook) on `session.created`
+ * and on the `experimental.session.compacting` event. If the bin emits a
+ * non-empty additionalContext envelope, the plugin:
+ *   1. Writes a clearly visible warning to `process.stderr` (TUI-visible)
+ *   2. Pushes the same message into `output.context` during compaction so
+ *      it survives compacted sessions
+ *
+ * Plain JavaScript (not TypeScript) — keeps the plugin runtime-portable
+ * with zero deps. opencode auto-installs deps declared in
+ * `.opencode/package.json` (per docs); we don't add any.
+ *
+ * Idempotent: if the plugin file already exists with identical content,
+ * leaves it alone. Re-runs of `wp setup` refresh this generated file to the
+ * current webpresso-owned content.
+ */
+import { join } from 'node:path';
+import { writeFileMerged } from '#cli/commands/init/merge';
+export const OPENCODE_PLUGIN_RELATIVE_PATH = '.opencode/plugins/webpresso-dev-link.js';
+export const OPENCODE_PLUGIN_CONTENT = `// Generated by webpresso (\`wp setup\`).
+//
+// Cross-runtime dev-link breakage warning for opencode. Mirrors the
+// SessionStart hook installed for Claude Code and Codex by shelling out
+// to the same \`wp-check-dev-link\` bin shipped with webpresso.
+//
+// The plugin emits the warning via stderr (visible in the opencode TUI)
+// on session.created, and pushes the same message into output.context
+// during compaction so it survives compacted sessions.
+//
+// Re-run \`wp setup\` to update this file. Delete it to opt out.
+
+const HOOK_BIN = './node_modules/.bin/wp-check-dev-link'
+
+async function detectBreakage($, directory) {
+  const result = await $\`bun \${HOOK_BIN}\`.cwd(directory).quiet().nothrow()
+  if (result.exitCode !== 0) return null
+  const stdout = result.stdout.toString().trim()
+  if (stdout === '') return null
+  try {
+    const envelope = JSON.parse(stdout)
+    return envelope?.hookSpecificOutput?.additionalContext ?? null
+  } catch {
+    return null
+  }
+}
+
+export const WebpressoDevLinkPlugin = async ({ $, directory }) => {
+  const reportIfBroken = async () => {
+    const message = await detectBreakage($, directory)
+    if (message !== null) process.stderr.write(\`\\n[opencode] \${message}\\n\\n\`)
+    return message
+  }
+
+  await reportIfBroken()
+
+  return {
+    event: async ({ event }) => {
+      if (event?.type === 'session.created') await reportIfBroken()
+    },
+    'experimental.session.compacting': async (_input, output) => {
+      const message = await reportIfBroken()
+      if (message !== null && output && Array.isArray(output.context)) {
+        output.context.push(message)
+      }
+    },
+  }
+}
+`;
+export function scaffoldOpencodePlugin(input) {
+    const targetPath = join(input.repoRoot, OPENCODE_PLUGIN_RELATIVE_PATH);
+    return writeFileMerged(targetPath, OPENCODE_PLUGIN_CONTENT, {
+        ...input.options,
+        ownership: 'generated-whole-file',
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/rtk/index.d.ts

@@ -0,0 +1,25 @@
+import { spawnSync } from 'node:child_process';
+import type { MergeOptions } from '#cli/commands/init/merge';
+import { type SpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+export interface EnsureRtkInput {
+    repoRoot: string;
+    options: MergeOptions;
+    spawn?: typeof spawnSync;
+    pinFilePath?: string;
+    strict?: boolean;
+    spinnerFactory?: SpinnerFactory;
+}
+export type EnsureRtkResult = {
+    kind: 'rtk-ok';
+    installed: boolean;
+} | {
+    kind: 'rtk-skipped-dry-run';
+} | {
+    kind: 'rtk-not-found';
+    hint: string;
+} | {
+    kind: 'rtk-init-failed';
+    exitCode: number;
+};
+export declare function ensureRtk(input: EnsureRtkInput): EnsureRtkResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/rtk/index.js

@@ -0,0 +1,55 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { makeNoopSpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+import { checkVersionPin } from '#cli/commands/init/scaffolders/version-pin';
+const NOT_FOUND_HINT = 'rtk is not on PATH. Install it manually (macOS: `brew install rtk`) and re-run.';
+export function ensureRtk(input) {
+    if (input.options.dryRun)
+        return { kind: 'rtk-skipped-dry-run' };
+    const spawn = input.spawn ?? spawnSync;
+    const spinner = (input.spinnerFactory ?? makeNoopSpinnerFactory())('rtk');
+    let installed = false;
+    spinner.start();
+    let probe = spawn('rtk', ['--version'], { encoding: 'utf8' });
+    if (probe.error || (probe.status !== null && probe.status !== 0)) {
+        if (process.platform !== 'darwin') {
+            spinner.fail('rtk not found');
+            return { kind: 'rtk-not-found', hint: NOT_FOUND_HINT };
+        }
+        const install = spawn('brew', ['install', 'rtk'], { stdio: 'inherit' });
+        if (install.status !== 0) {
+            spinner.fail('rtk install failed');
+            return { kind: 'rtk-not-found', hint: NOT_FOUND_HINT };
+        }
+        installed = true;
+        probe = spawn('rtk', ['--version'], { encoding: 'utf8' });
+        if (probe.error || (probe.status !== null && probe.status !== 0)) {
+            spinner.fail('rtk not found after install');
+            return { kind: 'rtk-not-found', hint: NOT_FOUND_HINT };
+        }
+    }
+    const installedVersion = String(probe.stdout ?? '').trim();
+    const pinCheck = checkVersionPin('rtk', installedVersion, input.pinFilePath ?? join(input.repoRoot, 'compatible-versions.json'));
+    if (!pinCheck.ok) {
+        if (input.strict) {
+            spinner.fail('rtk version mismatch');
+            return { kind: 'rtk-init-failed', exitCode: -1 };
+        }
+        console.warn(pinCheck.warning);
+    }
+    const result = spawn('rtk', ['init', '-g', '--auto-patch'], {
+        cwd: input.repoRoot,
+        stdio: 'inherit',
+        env: {
+            ...process.env,
+            RTK_TELEMETRY_DISABLED: '1',
+        },
+    });
+    if (result.status !== 0) {
+        spinner.fail('rtk init failed');
+        return { kind: 'rtk-init-failed', exitCode: result.status ?? -1 };
+    }
+    spinner.succeed('rtk ready');
+    return { kind: 'rtk-ok', installed };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/runtime-check/index.d.ts

@@ -0,0 +1,15 @@
+export interface RuntimeProbe {
+    name: string;
+    /** Returns the version string if found, null otherwise. */
+    detect: () => string | null;
+    /** Install hint shown when `detect()` returns null. */
+    hint: string;
+}
+export interface RuntimeStatus {
+    name: string;
+    version: string | null;
+    hint: string;
+}
+export declare const DEFAULT_PROBES: RuntimeProbe[];
+export declare function checkRuntimes(probes?: RuntimeProbe[]): RuntimeStatus[];
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/runtime-check/index.js

@@ -0,0 +1,37 @@
+/**
+ * Runtime detection for tools that webpresso consumers commonly need
+ * but that `wp setup` cannot install for them (curl-pipe install scripts
+ * or system package managers shouldn't be triggered silently).
+ *
+ * Auto-runs at the end of `wp setup`; prints a one-line status per
+ * runtime so the consumer knows what's missing without surprising them
+ * with a download.
+ */
+import { spawnSync } from 'node:child_process';
+function probeVersion(cmd, args = ['--version']) {
+    const r = spawnSync(cmd, args, { encoding: 'utf8' });
+    if (r.error || (r.status !== null && r.status !== 0))
+        return null;
+    return r.stdout.trim().split('\n')[0] ?? null;
+}
+export const DEFAULT_PROBES = [
+    {
+        name: 'bun',
+        detect: () => probeVersion('bun'),
+        hint: 'curl -fsSL https://bun.sh/install | bash   (or `brew install oven-sh/bun/bun`)',
+    },
+    {
+        name: 'vp',
+        detect: () => probeVersion('vp'),
+        hint: 'install vite-plus per your package manager (vp powers ingest-lens-style workspaces)',
+    },
+    {
+        name: 'actionlint',
+        detect: () => probeVersion('actionlint'),
+        hint: 'install actionlint (`brew install actionlint` or `go install github.com/rhysd/actionlint/cmd/actionlint@latest`)',
+    },
+];
+export function checkRuntimes(probes = DEFAULT_PROBES) {
+    return probes.map((p) => ({ name: p.name, version: p.detect(), hint: p.hint }));
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/spinner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DI-injectable spinner abstraction for scaffolders.
+ *
+ * Real usage: ora (TTY) or noop (non-TTY / CI).
+ * Test usage: inject a noop factory to track calls via vi.fn().
+ */
+export type Spinner = {
+    start(): void;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+};
+export type SpinnerFactory = (text: string) => Spinner;
+/**
+ * Returns the default spinner factory for the current environment.
+ * - Non-TTY (CI): always noop — no ANSI escape codes emitted.
+ * - TTY: ora-backed spinner.
+ */
+export declare function defaultSpinnerFactory(): Promise<SpinnerFactory>;
+/**
+ * Synchronous noop factory — safe for injection in tests and non-TTY paths.
+ */
+export declare function makeNoopSpinnerFactory(): SpinnerFactory;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/spinner.js

@@ -0,0 +1,32 @@
+/**
+ * DI-injectable spinner abstraction for scaffolders.
+ *
+ * Real usage: ora (TTY) or noop (non-TTY / CI).
+ * Test usage: inject a noop factory to track calls via vi.fn().
+ */
+const noopSpinner = {
+    start() { },
+    succeed() { },
+    fail() { },
+};
+function noopFactory(_text) {
+    return noopSpinner;
+}
+/**
+ * Returns the default spinner factory for the current environment.
+ * - Non-TTY (CI): always noop — no ANSI escape codes emitted.
+ * - TTY: ora-backed spinner.
+ */
+export async function defaultSpinnerFactory() {
+    if (!process.stdout.isTTY)
+        return noopFactory;
+    const { default: ora } = await import('ora');
+    return (text) => ora(text).start();
+}
+/**
+ * Synchronous noop factory — safe for injection in tests and non-TTY paths.
+ */
+export function makeNoopSpinnerFactory() {
+    return noopFactory;
+}
+//# sourceMappingURL=spinner.js.map

package/dist/esm/cli/commands/init/scaffolders/subagents/index.d.ts

@@ -0,0 +1,7 @@
+import type { MergeOptions, MergeResult } from '#cli/commands/init/merge';
+export interface ScaffoldSubagentsInput {
+    repoRoot: string;
+    options: MergeOptions;
+}
+export declare function scaffoldSubagents(input: ScaffoldSubagentsInput): MergeResult[];
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/subagents/index.js

@@ -0,0 +1,88 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync, } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readPackageJson } from '#cli/commands/init/detect-consumer';
+function detectMode(repoRoot) {
+    const pkg = readPackageJson(repoRoot).info;
+    if (pkg?.name === 'webpresso') {
+        return {
+            mode: 'self',
+            sourceRoot: join(repoRoot, 'catalog', 'agent', 'agents'),
+        };
+    }
+    const installedPackageJsonPath = join(repoRoot, 'node_modules', 'webpresso', 'package.json');
+    const installedAgentsRoot = join(repoRoot, 'node_modules', 'webpresso', 'catalog', 'agent', 'agents');
+    if (existsSync(installedPackageJsonPath) && existsSync(installedAgentsRoot)) {
+        return {
+            mode: 'consumer',
+            sourceRoot: installedAgentsRoot,
+        };
+    }
+    return {
+        mode: 'package-fallback',
+        sourceRoot: join(resolveCurrentPackageRoot(), 'catalog', 'agent', 'agents'),
+    };
+}
+function resolveCurrentPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth++) {
+        if (existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'catalog'))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('wp init: could not locate the webpresso package root for subagents fallback.');
+}
+export function scaffoldSubagents(input) {
+    const { repoRoot, options } = input;
+    const mode = detectMode(repoRoot);
+    const sourceRoot = mode.sourceRoot;
+    const targetRoot = join(repoRoot, '.claude', 'agents');
+    const results = [];
+    if (!existsSync(sourceRoot))
+        return results;
+    const entries = readdirSync(sourceRoot).filter((f) => f.endsWith('.md') && f !== 'README.md');
+    if (entries.length === 0)
+        return results;
+    if (!options.dryRun) {
+        mkdirSync(targetRoot, { recursive: true });
+    }
+    for (const name of entries) {
+        const sourcePath = join(sourceRoot, name);
+        const targetPath = join(targetRoot, name);
+        const symTarget = relative(dirname(targetPath), sourcePath);
+        if (options.dryRun) {
+            results.push({ targetPath, action: 'created' });
+            continue;
+        }
+        try {
+            const stat = lstatSync(targetPath);
+            if (stat.isSymbolicLink()) {
+                const currentTarget = readlinkSync(targetPath);
+                if (currentTarget === symTarget) {
+                    results.push({ targetPath, action: 'identical' });
+                }
+                else if (options.overwrite) {
+                    rmSync(targetPath);
+                    symlinkSync(symTarget, targetPath);
+                    results.push({ targetPath, action: 'overwritten' });
+                }
+                else {
+                    results.push({ targetPath, action: 'drifted' });
+                }
+            }
+            else {
+                results.push({ targetPath, action: 'identical' });
+            }
+        }
+        catch {
+            symlinkSync(symTarget, targetPath);
+            results.push({ targetPath, action: 'created' });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/version-pin.d.ts

@@ -0,0 +1,19 @@
+export type VersionPinTool = 'context_mode' | 'rtk';
+export type VersionPinResult = {
+    ok: true;
+} | {
+    ok: false;
+    warning: string;
+};
+/**
+ * Reads compatible-versions.json and checks whether `installedVersion`
+ * satisfies the pinned range for `tool`.
+ *
+ * @param tool             - 'context_mode' | 'rtk'
+ * @param installedVersion - the version string reported by the tool binary
+ * @param pinFilePath      - absolute path to compatible-versions.json; callers
+ *                           should pass `join(repoRoot, 'compatible-versions.json')`
+ *                           since scaffolders already have repoRoot from detectConsumer.
+ */
+export declare function checkVersionPin(tool: VersionPinTool, installedVersion: string, pinFilePath: string): VersionPinResult;
+//# sourceMappingURL=version-pin.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/version-pin.js

@@ -0,0 +1,95 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Parse a semver-like version string into [major, minor, patch].
+ * Strips leading 'v' and ignores pre-release/build metadata.
+ * Returns null if the version string is not parseable.
+ */
+function parseVersion(version) {
+    const cleaned = version.trim().replace(/^v/, '');
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(cleaned);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/**
+ * Minimal semver range check supporting the caret (^) operator only.
+ *
+ * ^X.Y.Z satisfies installed when:
+ *   installed.major === range.major AND installed >= range (minor+patch)
+ *
+ * For ^0.Y.Z (major === 0):
+ *   installed.major === 0 AND installed.minor === range.minor AND
+ *   installed.patch >= range.patch
+ *
+ * This matches npm's caret semantics without importing a semver library.
+ */
+function satisfiesRange(installed, range) {
+    const trimmedRange = range.trim();
+    if (trimmedRange.startsWith('^')) {
+        const pinned = parseVersion(trimmedRange.slice(1));
+        const actual = parseVersion(installed);
+        if (!pinned || !actual)
+            return false;
+        const [pinnedMajor, pinnedMinor, pinnedPatch] = pinned;
+        const [actualMajor, actualMinor, actualPatch] = actual;
+        if (pinnedMajor === 0) {
+            // ^0.Y.Z: minor must match, patch must be >=
+            if (actualMajor !== 0)
+                return false;
+            if (actualMinor !== pinnedMinor)
+                return false;
+            return actualPatch >= pinnedPatch;
+        }
+        // ^X.Y.Z (X > 0): major must match, (minor, patch) must be >=
+        if (actualMajor !== pinnedMajor)
+            return false;
+        if (actualMinor > pinnedMinor)
+            return true;
+        if (actualMinor < pinnedMinor)
+            return false;
+        return actualPatch >= pinnedPatch;
+    }
+    // Exact match fallback for bare "X.Y.Z" ranges
+    const pinned = parseVersion(trimmedRange);
+    const actual = parseVersion(installed);
+    if (!pinned || !actual)
+        return false;
+    return pinned[0] === actual[0] && pinned[1] === actual[1] && pinned[2] === actual[2];
+}
+/**
+ * Reads compatible-versions.json and checks whether `installedVersion`
+ * satisfies the pinned range for `tool`.
+ *
+ * @param tool             - 'context_mode' | 'rtk'
+ * @param installedVersion - the version string reported by the tool binary
+ * @param pinFilePath      - absolute path to compatible-versions.json; callers
+ *                           should pass `join(repoRoot, 'compatible-versions.json')`
+ *                           since scaffolders already have repoRoot from detectConsumer.
+ */
+export function checkVersionPin(tool, installedVersion, pinFilePath) {
+    const filePath = pinFilePath;
+    let pins;
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        pins = JSON.parse(raw);
+    }
+    catch {
+        // If the pin file is missing or malformed, treat as ok (non-blocking).
+        return { ok: true };
+    }
+    const pin = pins.pins[tool];
+    if (!pin)
+        return { ok: true };
+    const range = pin.range;
+    if (!range)
+        return { ok: true };
+    if (satisfiesRange(installedVersion, range)) {
+        return { ok: true };
+    }
+    const toolLabel = tool === 'context_mode' ? 'context-mode' : 'rtk';
+    return {
+        ok: false,
+        warning: `[webpresso] ${toolLabel} version ${installedVersion} does not satisfy the required range ${range} (from compatible-versions.json). Some features may not work as expected. Update ${toolLabel} to a compatible version.`,
+    };
+}
+//# sourceMappingURL=version-pin.js.map

package/dist/esm/cli/commands/init/scaffolders/vision/index.d.ts

@@ -0,0 +1,10 @@
+import { type MergeOptions, type MergeResult } from '#cli/commands/init/merge';
+import type { VisionAnswers } from './interview.js';
+export interface ScaffoldVisionInput {
+    catalogDir: string;
+    repoRoot: string;
+    options: MergeOptions;
+    answers?: VisionAnswers | null;
+}
+export declare function scaffoldVision(input: ScaffoldVisionInput): MergeResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/vision/index.js

@@ -0,0 +1,67 @@
+/**
+ * `vision` scaffolder preset.
+ *
+ * Drops a starter `VISION.md` at repo root from `catalog/vision/VISION.md.tmpl`
+ * with `{{REPO_NAME}}`, `{{TODAY}}`, and (optionally) interview-derived
+ * substitutions. Idempotent: existing files are protected by the standard
+ * merge policy (reported as drift unless `--overwrite`).
+ *
+ * When `answers` is provided (from `maybeRunVisionInterview`), the
+ * placeholders `{{ONE_LINER}}`, `{{PROBLEM}}`, `{{TAGLINE}}`, `{{IN_SCOPE}}`,
+ * `{{OUT_OF_SCOPE}}`, and `{{PRINCIPLES}}` are replaced with the operator's
+ * own words. Skipped fields fall back to the original prose stubs so the
+ * audit (`wp audit vision`) still passes minimally.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { writeFileMerged } from '#cli/commands/init/merge';
+export function scaffoldVision(input) {
+    const templatePath = path.join(input.catalogDir, 'vision', 'VISION.md.tmpl');
+    if (!existsSync(templatePath)) {
+        throw new Error(`vision scaffolder: template not found at ${templatePath}`);
+    }
+    const template = readFileSync(templatePath, 'utf8');
+    const today = new Date().toISOString().slice(0, 10);
+    const repoName = path.basename(input.repoRoot);
+    const rendered = applyAnswers(template, repoName, today, input.answers ?? null);
+    const target = path.join(input.repoRoot, 'VISION.md');
+    return writeFileMerged(target, rendered, input.options);
+}
+const STUB = {
+    oneLiner: 'One-line summary of what this repo does. Replace this with a real description before merging.',
+    problem: 'What problem does this repo solve? What pain exists today that this work addresses? 2-4 sentences. Be concrete — name the actors and the friction.',
+    tagline: 'One-line tagline that fits on a sticker.',
+    inScope: ['- Things this repo owns.', '- Surfaces it presents to consumers.'].join('\n'),
+    outOfScope: [
+        '- Things that look related but belong elsewhere — name where they belong.',
+        '- Hypothetical "could fit here" scope that isn\'t earning its keep.',
+    ].join('\n'),
+    principles: [
+        '- Principle 1 — short rationale.',
+        '- Principle 2 — short rationale.',
+        '- Principle 3 — short rationale.',
+    ].join('\n'),
+};
+function applyAnswers(template, repoName, today, answers) {
+    return template
+        .replaceAll('{{REPO_NAME}}', repoName)
+        .replaceAll('{{TODAY}}', today)
+        .replaceAll('{{ONE_LINER}}', nonEmpty(answers?.oneLiner) ?? STUB.oneLiner)
+        .replaceAll('{{PROBLEM}}', nonEmpty(answers?.problem) ?? STUB.problem)
+        .replaceAll('{{TAGLINE}}', nonEmpty(answers?.tagline) ?? STUB.tagline)
+        .replaceAll('{{IN_SCOPE}}', renderList(answers?.inScope) ?? STUB.inScope)
+        .replaceAll('{{OUT_OF_SCOPE}}', renderList(answers?.outOfScope) ?? STUB.outOfScope)
+        .replaceAll('{{PRINCIPLES}}', renderList(answers?.principles) ?? STUB.principles);
+}
+function nonEmpty(value) {
+    if (value === undefined)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function renderList(items) {
+    if (!items || items.length === 0)
+        return null;
+    return items.map((item) => `- ${item}`).join('\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/vision/interview.d.ts

@@ -0,0 +1,22 @@
+export interface VisionInterviewInput {
+    repoName: string;
+    isTTY?: boolean;
+    yesFlag?: boolean;
+    visionExists: boolean;
+    inputStream?: NodeJS.ReadableStream;
+    outputStream?: NodeJS.WritableStream;
+}
+export interface VisionAnswers {
+    oneLiner: string;
+    tagline: string;
+    problem: string;
+    inScope: readonly string[];
+    outOfScope: readonly string[];
+    principles: readonly string[];
+}
+/**
+ * Returns answers to interpolate into the template, or `null` if the
+ * interview should not run (non-TTY, --yes, or VISION.md already exists).
+ */
+export declare function maybeRunVisionInterview(input: VisionInterviewInput): Promise<VisionAnswers | null>;
+//# sourceMappingURL=interview.d.ts.map