@kindgi/cli 0.0.0-bootstrap.0 → 0.1.0

package/dist/help.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { ROOT_COMMANDS } from './commands/index.js';
+import { wiredCommands } from './commands/unwired.js';
+import { GLOBAL_OPTION_SPEC } from './parse.js';
+export function rootHelpText() {
+    const lines = [];
+    lines.push('kindgi — command-line interface for Kindgi™ — the sovereign AI OS');
+    lines.push('');
+    lines.push('Usage: kindgi <command> [<subcommand>] [args] [flags]');
+    lines.push('');
+    lines.push('Commands:');
+    for (const c of wiredCommands(ROOT_COMMANDS)) {
+        lines.push(`  ${c.name.padEnd(16, ' ')}  ${c.description}`);
+    }
+    lines.push('');
+    lines.push('Global flags:');
+    lines.push(...flagLines(GLOBAL_OPTION_SPEC));
+    lines.push('');
+    lines.push('Config precedence: --flag > env var > .kindgirc.json (this directory) > ~/.kindgi/config.json.');
+    return `${lines.join('\n')}\n`;
+}
+/** `path`: the command's words from the root, so a group lists only its wired subcommands. */
+export function commandHelpText(command, path = [command.name]) {
+    const lines = [];
+    lines.push(command.description);
+    lines.push('');
+    if (command.kind === 'leaf') {
+        lines.push(`Usage: ${command.usage}`);
+        const flags = flagLines(command.optionSpec ?? {});
+        if (flags.length > 0) {
+            lines.push('');
+            lines.push('Flags:');
+            lines.push(...flags);
+        }
+        lines.push('');
+        lines.push('Global flags (--json, --url, --token, …): kindgi --help');
+    }
+    else {
+        lines.push(`Usage: kindgi ${command.name} <subcommand> [args] [flags]`);
+        lines.push('');
+        lines.push('Subcommands:');
+        for (const sub of wiredCommands(command.subcommands, path)) {
+            lines.push(`  ${sub.name.padEnd(16, ' ')}  ${sub.description}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** `  --name <value>, -n   What it does.`, one line per flag, by name. */
+function flagLines(spec) {
+    const rows = Object.entries(spec)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, option]) => {
+        const value = option.type === 'string' ? (option.optionalValue ? '[=<value>]' : ' <value>') : '';
+        const short = option.short ? `, -${option.short}` : '';
+        return [`--${name}${value}${short}`, option.description ?? ''];
+    });
+    const width = Math.max(0, ...rows.map(([label]) => label.length));
+    return rows.map(([label, description]) => `  ${label.padEnd(width)}  ${description}`.trimEnd());
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @kindgi/cli — the `kindgi` command-line interface.
+ *
+ * Projects add it as a devDependency and run `kindgi` through their
+ * package manager (`pnpm exec kindgi …`). The programmatic surface below
+ * is exposed for tests and for tools that embed CLI behavior without
+ * spawning a subprocess.
+ */
+export { runCli } from './main.js';
+export type { CliOutcome, RunCliInputs } from './main.js';
+export { describeCommands, describeGlobalFlags } from './reference.js';
+export type { CommandReference, FlagReference } from './reference.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * @kindgi/cli — the `kindgi` command-line interface.
+ *
+ * Projects add it as a devDependency and run `kindgi` through their
+ * package manager (`pnpm exec kindgi …`). The programmatic surface below
+ * is exposed for tests and for tools that embed CLI behavior without
+ * spawning a subprocess.
+ */
+export { runCli } from './main.js';
+export { describeCommands, describeGlobalFlags } from './reference.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/init/augment-scaffolder.d.ts

@@ -0,0 +1,74 @@
+import type { CommandResult } from '../commands/types.js';
+import { type PackageManager } from '../package-manager.js';
+import { type KindgiDependencySpecs } from './dependency-specs.js';
+export interface RunInitAugmentInputs {
+    readonly targetDir: string;
+    /**
+     * Optional root containing shipped skill folders (each with a
+     * `SKILL.md`). If undefined, no skills are copied. Production
+     * wiring passes `defaultSdkSkillsRoot()`; tests inject a fixture
+     * dir.
+     */
+    readonly skillsRoot?: string;
+    /** Override the derived pack id (e.g. when name normalization can't produce a valid PACK_ID). */
+    readonly packIdOverride?: string;
+    /**
+     * Overwrite existing `kindgi.config.ts` + shipped skill files under
+     * `.claude/skills/kindgi-<name>/SKILL.md`. Non-force default:
+     * refuse when `kindgi.config.ts` exists; merge (skip) any
+     * pre-existing skill files.
+     */
+    readonly force: boolean;
+    /** `--link-local`: link the Kindgi checkout even when the target is inside its workspace. */
+    readonly linkLocal?: boolean;
+    /**
+     * `--template`: `sample` adds the sample pack's primitives (tools, a
+     * guardrail, an agent, a flow) under `kindgi/`, read from
+     * `templatesRoot`. Default `minimal`: the config and empty folders.
+     */
+    readonly template?: 'minimal' | 'sample';
+    readonly templatesRoot?: string;
+    /** Test seams. */
+    readonly ioOverrides?: AugmentIOOverrides;
+    readonly packageManager?: PackageManager;
+    readonly dependencySpecs?: KindgiDependencySpecs;
+}
+export interface AugmentIOOverrides {
+    readonly readFile?: (path: string) => Promise<string>;
+    readonly writeFile?: (path: string, contents: string) => Promise<void>;
+    readonly mkdir?: (path: string) => Promise<void>;
+    readonly fileExists?: (path: string) => Promise<boolean>;
+    readonly listDir?: (path: string) => Promise<readonly string[]>;
+}
+/**
+ * Derive a `PACK_ID_REGEX`-valid id from a `package.json` name. Rules:
+ *   - `my-app` -> `my-app`
+ *   - `@acme/legal` -> `acme.legal`
+ *   - `@ACME/Legal` -> `acme.legal`  (lowercased)
+ *   - `my_app` -> error (underscores not allowed; explicit override required)
+ *   - `x` (single char, valid) -> `x`
+ */
+export declare function derivePackId(name: string): {
+    readonly kind: 'ok';
+    readonly id: string;
+} | {
+    readonly kind: 'err';
+    readonly message: string;
+};
+/**
+ * Render the augment-mode `kindgi.config.ts` file. Compact — no
+ * `environments` block (user fills that in when ready to deploy;
+ * `kindgi dev` doesn't need it).
+ */
+export declare function renderAugmentConfig(inputs: {
+    readonly packId: string;
+    readonly packVersion: string;
+    readonly packName: string;
+}): string;
+export declare function runInitAugment(inputs: RunInitAugmentInputs): Promise<CommandResult>;
+/**
+ * What to run next — in the project's own package manager, with its own
+ * `kindgi`. With the sample's `packId`, how to try its agent too.
+ */
+export declare function augmentNextSteps(pm: PackageManager, samplePackId?: string): readonly string[];
+//# sourceMappingURL=augment-scaffolder.d.ts.map

package/dist/init/augment-scaffolder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment-scaffolder.d.ts","sourceRoot":"","sources":["../../src/init/augment-scaffolder.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EACL,KAAK,cAAc,EAIpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,qBAAqB,EAAgC,MAAM,uBAAuB,CAAC;AAUjG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iGAAiG;IACjG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAEV;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAkBrD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CA6BT;AAuCD,wBAAsB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmHzF;AAwCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAmB7F"}

package/dist/init/augment-scaffolder.js

@@ -0,0 +1,459 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Augment-mode scaffolder — writes Kindgi files ALONGSIDE an existing
+ * Node.js project. Called from `runInit` when `detectInitMode` returns
+ * `mode: 'augment'`.
+ *
+ * What augment mode writes:
+ *   - `kindgi.config.ts` at project root — `kindgi.config.mts` when the
+ *     app is CommonJS (no `"type": "module"`), plus a one-line
+ *     `kindgi/package.json` marking `kindgi/` as ES modules, so Node
+ *     never reparses Kindgi's files with a warning (pack id derived from
+ *     `package.json` `name`, discovery paths point at `kindgi/**`)
+ *   - `kindgi/agents/.gitkeep`
+ *   - `kindgi/tools/.gitkeep`
+ *   - `kindgi/guardrails/.gitkeep`
+ *   - `kindgi/flows/.gitkeep`
+ *   - `.claude/skills/kindgi-<name>/SKILL.md` for each shipped skill —
+ *     merge-not-overwrite: skips files that already exist so user
+ *     customizations survive
+ *   - `package.json`: `@kindgi/sdk` (dependency) + `@kindgi/cli`
+ *     (devDependency), specs from `resolveKindgiDependencySpecs` — the
+ *     project runs its own pinned `kindgi`
+ *   - `.gitignore`: Kindgi's local-state patterns
+ *
+ * What augment mode does NOT write:
+ *   - env files — `kindgi dev` reads the project's own `.env` /
+ *     `.env.local`; nothing needs creating
+ *   - `pnpm-workspace.yaml`, `tsconfig.json`, `vitest.config.ts`,
+ *     `.nvmrc`, `AGENTS.md`, `README.md` — the surrounding repo owns
+ *     these; we don't touch them
+ *
+ * @related packages/cli/src/init/mode-detect.ts (the branch)
+ * @related packages/cli/src/commands/init.ts (the caller)
+ */
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { KINDGI_CONFIG_FILENAMES } from '@kindgi/handler-runtime';
+import { PACK_ID_REGEX } from '../commands/init.js';
+import { syncSkills } from '../commands/skills.js';
+import { renderJson } from '../output.js';
+import { binDisplay, detectPackageManager, installCommand, } from '../package-manager.js';
+import { resolveKindgiDependencySpecs } from './dependency-specs.js';
+import { patchGitignore, patchPrettierignore } from './gitignore-patcher.js';
+import { patchPackageJson } from './package-json-patcher.js';
+import { collectTemplateFiles, substitute } from './template-files.js';
+const DEFAULT_PACK_ID_FALLBACK = 'kindgi-pack';
+const DEFAULT_PACK_VERSION_FALLBACK = '0.1.0';
+const AUGMENT_SUBDIRS = ['agents', 'tools', 'guardrails', 'flows'];
+/**
+ * Derive a `PACK_ID_REGEX`-valid id from a `package.json` name. Rules:
+ *   - `my-app` -> `my-app`
+ *   - `@acme/legal` -> `acme.legal`
+ *   - `@ACME/Legal` -> `acme.legal`  (lowercased)
+ *   - `my_app` -> error (underscores not allowed; explicit override required)
+ *   - `x` (single char, valid) -> `x`
+ */
+export function derivePackId(name) {
+    if (name === '') {
+        return {
+            kind: 'err',
+            message: 'package.json name is empty. Pass `--pack-id=<id>` explicitly.',
+        };
+    }
+    const lower = name.toLowerCase();
+    // Scoped: `@scope/pkg` → `scope.pkg`
+    const scopedMatch = lower.match(/^@([^/]+)\/(.+)$/);
+    const candidate = scopedMatch !== null ? `${scopedMatch[1]}.${scopedMatch[2]}` : lower;
+    if (!PACK_ID_REGEX.test(candidate)) {
+        return {
+            kind: 'err',
+            message: `Cannot derive a valid pack id from package.json name "${name}" (candidate: "${candidate}").\nPack ids must match ${PACK_ID_REGEX.source} — lowercase kebab, optionally dot-namespaced.\nPass \`--pack-id=<id>\` to override, e.g. \`--pack-id=my-pack\`.\n`,
+        };
+    }
+    return { kind: 'ok', id: candidate };
+}
+/**
+ * Render the augment-mode `kindgi.config.ts` file. Compact — no
+ * `environments` block (user fills that in when ready to deploy;
+ * `kindgi dev` doesn't need it).
+ */
+export function renderAugmentConfig(inputs) {
+    return `// Kindgi pack config — added by \`kindgi init\` (augment mode).
+// The pack lives alongside your existing code; discovery paths below
+// scope Kindgi to \`kindgi/**\` so authoring stays isolated from the
+// surrounding app's code.
+
+const config = {
+  pack: {
+    id: '${inputs.packId}',
+    version: '${inputs.packVersion}',
+    description: 'Kindgi pack embedded in ${inputs.packName}.',
+  },
+  discovery: {
+    tools: 'kindgi/tools/**/*.ts',
+    guardrails: 'kindgi/guardrails/**/*.ts',
+    agents: 'kindgi/agents/**/*.ts',
+    flows: 'kindgi/flows/**/*.ts',
+  },
+  // ---------------------------------------------------------------
+  // Environments — fill in when you're ready to push a build off the
+  // laptop. See the minimal template's kindgi.config.ts for the full
+  // shape (endpoint / build / registry / signingKey / tenantId per
+  // environment). Local \`kindgi dev\` doesn't read this block.
+  // ---------------------------------------------------------------
+  environments: {},
+} as const;
+
+export default config;
+`;
+}
+const defaultIO = {
+    readFile: (path) => readFile(path, 'utf8'),
+    writeFile: async (path, contents) => {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, contents, 'utf8');
+    },
+    mkdir: (path) => mkdir(path, { recursive: true }).then(() => undefined),
+    fileExists: async (path) => {
+        try {
+            const s = await stat(path);
+            return s.isFile();
+        }
+        catch {
+            return false;
+        }
+    },
+    listDir: async (path) => {
+        const { readdir } = await import('node:fs/promises');
+        try {
+            return await readdir(path);
+        }
+        catch {
+            return [];
+        }
+    },
+};
+export async function runInitAugment(inputs) {
+    const io = { ...defaultIO, ...inputs.ioOverrides };
+    const pkgJsonPath = join(inputs.targetDir, 'package.json');
+    const readResult = await readSourcePackageJson(io, pkgJsonPath);
+    if (readResult.kind === 'err') {
+        return { kind: 'error', stderr: readResult.stderr, exitCode: 1 };
+    }
+    const pkgJson = readResult.pkg;
+    const rawName = typeof pkgJson.name === 'string' ? pkgJson.name : '';
+    const packName = rawName === '' ? DEFAULT_PACK_ID_FALLBACK : rawName;
+    const packVersion = typeof pkgJson.version === 'string' && pkgJson.version !== ''
+        ? pkgJson.version
+        : DEFAULT_PACK_VERSION_FALLBACK;
+    const packIdResult = resolvePackId(rawName, inputs.packIdOverride);
+    if (packIdResult.kind === 'err') {
+        return { kind: 'error', stderr: packIdResult.stderr, exitCode: 1 };
+    }
+    const packId = packIdResult.id;
+    const existing = await findExistingConfig(io, inputs.targetDir);
+    if (existing !== undefined && !inputs.force) {
+        return {
+            kind: 'error',
+            stderr: `${existing} already exists.\nRe-run with --force to overwrite the pack config (skills are always merged, not overwritten, unless --force is also set).\n`,
+            exitCode: 1,
+        };
+    }
+    // A CommonJS app (no `"type": "module"`) would make Node reparse a
+    // `.ts` config / primitive as ESM with a warning on every run.
+    const esmApp = pkgJson.type === 'module';
+    const configPath = existing ?? join(inputs.targetDir, esmApp ? 'kindgi.config.ts' : 'kindgi.config.mts');
+    // Resolve how the project will depend on Kindgi BEFORE writing
+    // anything, so a failure leaves the repo untouched.
+    const deps = await resolveProjectDeps(inputs);
+    if (deps.kind === 'err')
+        return { kind: 'error', stderr: deps.stderr, exitCode: 1 };
+    const filesWritten = await writeAugmentFiles({
+        io,
+        targetDir: inputs.targetDir,
+        configPath,
+        packId,
+        packVersion,
+        packName,
+        skillsRoot: inputs.skillsRoot,
+        force: inputs.force,
+        esmApp,
+    });
+    const created = [...filesWritten.created];
+    const skipped = [...filesWritten.skipped];
+    const sample = inputs.template === 'sample' && inputs.templatesRoot !== undefined;
+    if (sample) {
+        const primitives = await writeSamplePrimitives({
+            io,
+            sampleDir: join(inputs.templatesRoot, 'sample'),
+            targetDir: inputs.targetDir,
+            substitutions: { PACK_NAME: packName, PACK_ID: packId, PACK_VERSION: packVersion },
+            force: inputs.force,
+        });
+        created.push(...primitives.created);
+        skipped.push(...primitives.skipped);
+    }
+    const patchResult = await applyAugmentPatches({
+        targetDir: inputs.targetDir,
+        pkgJsonPath,
+        specs: deps.specs,
+        // The sample tools' schemas are Zod. An app with Zod keeps its own.
+        ...(sample && { extraDependencies: [SAMPLE_ZOD_DEPENDENCY] }),
+    });
+    if (patchResult.kind === 'err') {
+        return { kind: 'error', stderr: patchResult.stderr, exitCode: 1 };
+    }
+    created.push(...patchResult.created);
+    skipped.push(...patchResult.skipped);
+    const nextSteps = augmentNextSteps(deps.packageManager, sample ? packId : undefined);
+    const summary = {
+        kind: 'augment',
+        targetDir: inputs.targetDir,
+        packId,
+        packVersion,
+        packageManager: deps.packageManager,
+        dependencies: deps.specs,
+        created,
+        skipped,
+        nextSteps,
+    };
+    const rendered = renderJson(summary, 'json');
+    return {
+        kind: 'ok',
+        rendered: {
+            stdout: rendered.stdout,
+            stderr: [
+                '',
+                `  Kindgi added to ${inputs.targetDir} (augment mode).`,
+                `  Pack id: ${packId}    Version: ${packVersion}`,
+                `  Wrote ${created.length} file${created.length === 1 ? '' : 's'}; skipped ${skipped.length}.`,
+                '',
+                '  Next steps:',
+                ...nextSteps.map((step) => `    ${step}`),
+                '',
+                '',
+            ].join('\n'),
+        },
+    };
+}
+// ---------------------------------------------------------------------
+// Extracted helpers — keep runInitAugment under the complexity ceiling.
+// ---------------------------------------------------------------------
+/** The first `kindgi.config.*` already at the root, if any. */
+async function findExistingConfig(io, targetDir) {
+    for (const name of KINDGI_CONFIG_FILENAMES) {
+        const path = join(targetDir, name);
+        if (await io.fileExists(path))
+            return path;
+    }
+    return undefined;
+}
+async function resolveProjectDeps(inputs) {
+    const packageManager = inputs.packageManager ?? (await detectPackageManager(inputs.targetDir));
+    if (inputs.dependencySpecs !== undefined) {
+        return { kind: 'ok', packageManager, specs: inputs.dependencySpecs };
+    }
+    const resolved = await resolveKindgiDependencySpecs({
+        targetDir: inputs.targetDir,
+        packageManager,
+        ...(inputs.linkLocal === true && { forceLocal: true }),
+    });
+    if (resolved.kind === 'error')
+        return { kind: 'err', stderr: `${resolved.message}\n` };
+    return { kind: 'ok', packageManager, specs: resolved.specs };
+}
+/**
+ * What to run next — in the project's own package manager, with its own
+ * `kindgi`. With the sample's `packId`, how to try its agent too.
+ */
+export function augmentNextSteps(pm, samplePackId) {
+    const setSecret = binDisplay(pm, 'kindgi', [
+        'secrets',
+        'set',
+        '<NAME>',
+        '--env=local',
+        '--scope=tenant',
+    ]);
+    return [
+        `Install: ${installCommand(pm)}`,
+        `Boot the dev server: ${binDisplay(pm, 'kindgi', ['dev'])}`,
+        `Secrets: kindgi dev reads your .env and .env.local — keys there are available, or run ${setSecret}`,
+        `Model provider: agents answer with the dev-echo fallback until you register one — e.g. ${binDisplay(pm, 'kindgi', ['providers', 'register', '--preset=anthropic'])} (ANTHROPIC_API_KEY in .env); more in .claude/skills/kindgi-authoring-providers/SKILL.md`,
+        ...(samplePackId === undefined
+            ? []
+            : [
+                `Try the sample agent: ${binDisplay(pm, 'kindgi', ['runs', 'start', `--agent=${samplePackId}.echo-agent`, `--input='{"userMessage":"hi"}'`])}`,
+            ]),
+    ];
+}
+/** The sample's primitive folders, as augment mode lays them out under `kindgi/`. */
+const SAMPLE_PRIMITIVE_DIRS = ['agents', 'flows', 'guardrails', 'tools'];
+const SAMPLE_ZOD_DEPENDENCY = { name: 'zod', spec: '^4.0.0', section: 'dependencies' };
+/**
+ * Copy the sample pack's primitives into `kindgi/<kind>/`, rendered as a
+ * fresh sample pack renders them. The sample's tests stay out: the app
+ * has its own test setup. A file already there is kept unless `force`.
+ */
+async function writeSamplePrimitives(args) {
+    const created = [];
+    const skipped = [];
+    for (const kind of SAMPLE_PRIMITIVE_DIRS) {
+        const files = await collectTemplateFiles(join(args.sampleDir, kind));
+        for (const rel of files.sort()) {
+            if (/\.test\.ts(\.tmpl)?$/.test(rel))
+                continue;
+            const targetRel = rel.endsWith('.tmpl') ? rel.slice(0, -'.tmpl'.length) : rel;
+            const dest = join(args.targetDir, 'kindgi', kind, targetRel);
+            if (!args.force && (await args.io.fileExists(dest))) {
+                skipped.push(dest);
+                continue;
+            }
+            const raw = await args.io.readFile(join(args.sampleDir, kind, rel));
+            await args.io.writeFile(dest, rel.endsWith('.tmpl') ? substitute(raw, args.substitutions) : raw);
+            created.push(dest);
+        }
+    }
+    return { created, skipped };
+}
+async function readSourcePackageJson(io, pkgJsonPath) {
+    let raw;
+    try {
+        raw = await io.readFile(pkgJsonPath);
+    }
+    catch (err) {
+        return { kind: 'err', stderr: `Failed to read ${pkgJsonPath}: ${err.message}\n` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            kind: 'err',
+            stderr: `Failed to parse ${pkgJsonPath}: ${err.message}\n`,
+        };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { kind: 'err', stderr: `${pkgJsonPath} is not a JSON object.\n` };
+    }
+    return { kind: 'ok', pkg: parsed };
+}
+function resolvePackId(rawName, override) {
+    if (override !== undefined && override !== '') {
+        if (!PACK_ID_REGEX.test(override)) {
+            return {
+                kind: 'err',
+                stderr: `Invalid --pack-id: ${override}. Must match ${PACK_ID_REGEX.source}.\n`,
+            };
+        }
+        return { kind: 'ok', id: override };
+    }
+    const derived = derivePackId(rawName);
+    if (derived.kind === 'err')
+        return { kind: 'err', stderr: derived.message };
+    return { kind: 'ok', id: derived.id };
+}
+/**
+ * Write the deterministic parts of the augment scaffold: config,
+ * subdirs, skills (merge/force respected). Returns the (created,
+ * skipped) split so the caller can still append patcher results.
+ */
+async function writeAugmentFiles(args) {
+    const created = [];
+    const skipped = [];
+    // Config.
+    await args.io.writeFile(args.configPath, renderAugmentConfig({
+        packId: args.packId,
+        packVersion: args.packVersion,
+        packName: args.packName,
+    }));
+    created.push(args.configPath);
+    // Subdirs.
+    for (const sub of AUGMENT_SUBDIRS) {
+        const gitkeep = join(args.targetDir, 'kindgi', sub, '.gitkeep');
+        await args.io.writeFile(gitkeep, '');
+        created.push(gitkeep);
+    }
+    // In a CommonJS app, mark `kindgi/` as ES modules so primitives stay
+    // plain `.ts`. Never overwrite one the author already has.
+    if (!args.esmApp) {
+        const marker = join(args.targetDir, 'kindgi', 'package.json');
+        if (await args.io.fileExists(marker)) {
+            skipped.push(marker);
+        }
+        else {
+            await args.io.writeFile(marker, `${JSON.stringify({ type: 'module' }, null, 2)}\n`);
+            created.push(marker);
+        }
+    }
+    // Skills — through `kindgi skills sync`'s own path, so the manifest
+    // it keeps is written too (without it, `kindgi dev` reports every
+    // freshly installed skill as out of date). Local edits are kept
+    // unless --force.
+    if (args.skillsRoot !== undefined) {
+        const report = await syncSkills({
+            skillsRoot: args.skillsRoot,
+            targetDir: args.targetDir,
+            language: 'node',
+            force: args.force,
+            dryRun: false,
+        });
+        for (const o of report.outcomes) {
+            const target = join(args.targetDir, '.claude', 'skills', o.name, 'SKILL.md');
+            if (o.status === 'added' || o.status === 'updated')
+                created.push(target);
+            else if (o.status !== 'local-only')
+                skipped.push(target);
+        }
+    }
+    return { created, skipped };
+}
+/**
+ * Apply the two file patchers (package.json + .gitignore) and turn
+ * their outcomes into (created, skipped) rows for the summary.
+ * Extracted so `runInitAugment` stays under the complexity ceiling.
+ */
+async function applyAugmentPatches(args) {
+    const created = [];
+    const skipped = [];
+    const patchPkg = await patchPackageJson(args.pkgJsonPath, args.specs, args.extraDependencies);
+    if (patchPkg.kind === 'error') {
+        return { kind: 'err', stderr: `Failed to patch ${args.pkgJsonPath}: ${patchPkg.message}\n` };
+    }
+    if (patchPkg.kind === 'patched') {
+        created.push(`${args.pkgJsonPath} (patched: +${patchPkg.added.join(', +')})`);
+    }
+    else {
+        skipped.push(`${args.pkgJsonPath} (dependencies already declared)`);
+    }
+    const gitignorePath = join(args.targetDir, '.gitignore');
+    const patchGit = await patchGitignore(gitignorePath);
+    if (patchGit.kind === 'error') {
+        return {
+            kind: 'err',
+            stderr: `Failed to patch ${gitignorePath}: ${patchGit.message ?? 'unknown error'}\n`,
+        };
+    }
+    if (patchGit.kind === 'patched') {
+        created.push(`${gitignorePath} (patched: +${patchGit.appended.join(', +')})`);
+    }
+    else {
+        skipped.push(`${gitignorePath} (Kindgi patterns already present)`);
+    }
+    // The app's formatter must not rewrite the Kindgi-managed skills.
+    const prettierignorePath = join(args.targetDir, '.prettierignore');
+    const patchPrettier = await patchPrettierignore(prettierignorePath);
+    if (patchPrettier.kind === 'error') {
+        return {
+            kind: 'err',
+            stderr: `Failed to patch ${prettierignorePath}: ${patchPrettier.message}\n`,
+        };
+    }
+    if (patchPrettier.kind === 'patched') {
+        created.push(`${prettierignorePath} (patched: +${patchPrettier.appended.join(', +')})`);
+    }
+    return { kind: 'ok', created, skipped };
+}
+//# sourceMappingURL=augment-scaffolder.js.map