@keystrokehq/cli 0.0.1

package/dist/init-DpMCotSK.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { t as createTypedCommand } from "./commander-DfTVqQ-3.mjs";
+import { z } from "zod";
+//#region src/commands/init/init.command.ts
+const InitOptionsSchema = z.object({
+	path: z.string().optional().describe("Directory to initialize (default: current directory)"),
+	name: z.string().optional().describe("Project name (skips prompt; default: directory basename)"),
+	description: z.string().optional().describe("Project description for the API (skips prompt when creating a new project)"),
+	scaffold: z.boolean().default(true).describe("Scaffold project files (package.json, vitest.config.ts, etc.)"),
+	install: z.boolean().default(true).describe("Run package manager install after scaffolding (when scaffold is enabled)")
+});
+const INIT_OPTIONS_CONFIG = {
+	path: {
+		flag: "--path <dir>",
+		description: "Directory to initialize (default: current directory)"
+	},
+	name: {
+		flag: "--name <name>",
+		description: "Project name (non-interactive; default: directory basename)"
+	},
+	description: {
+		flag: "--description <text>",
+		description: "Project description when creating the remote project (non-interactive)"
+	},
+	scaffold: {
+		flag: "--no-scaffold",
+		description: "Skip scaffolding project files (package.json, vitest.config.ts, etc.)"
+	},
+	install: {
+		flag: "--no-install",
+		description: "Skip running package manager install after scaffolding"
+	}
+};
+function createInitCommand() {
+	return createTypedCommand({
+		name: "init",
+		description: "Initialize a Keystroke project (creates keystroke.config.ts)",
+		schema: InitOptionsSchema,
+		optionsConfig: INIT_OPTIONS_CONFIG,
+		loadHandler: async () => (await import("./init.handler-CPRnif52.mjs")).handleInit
+	});
+}
+//#endregion
+export { createInitCommand };

package/dist/init.handler-CPRnif52.mjs

@@ -0,0 +1,585 @@
+#!/usr/bin/env node
+
+import { C as CliExitError, t as ui } from "./keystroke.mjs";
+import { d as trackProject } from "./dist-CUK7yBM0.mjs";
+import { a as writeProjectConfig, i as readProjectConfig, r as getProjectConfigPath } from "./project-config-D1qsQlO7.mjs";
+import { i as requireClient } from "./context-T7HZuB97.mjs";
+import { t as syncKeystrokeAgentSkills } from "./sync-keystroke-agent-skills-Kx_H7UTd.mjs";
+import { createRequire } from "node:module";
+import { accessSync, readFileSync } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import * as path$1 from "node:path";
+import path from "node:path";
+import { cancel, isCancel, text } from "@clack/prompts";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+//#region src/lib/keystroke-local-registry-npmrc.ts
+/**
+* Default local registry for consumer projects (Verdaccio default port).
+* Override with `KEYSTROKE_LOCAL_NPM_REGISTRY` when publishing or documenting for authors.
+*/
+function getKeystrokeLocalNpmRegistryUrl() {
+	const raw = process.env.KEYSTROKE_LOCAL_NPM_REGISTRY?.trim();
+	if (!raw) return "http://localhost:4873/";
+	return `${raw.replace(/\/+$/, "")}/`;
+}
+/**
+* `.npmrc` line so installs resolve `@keystroke/*` from the local registry (Verdaccio).
+*/
+function createKeystrokeLocalRegistryNpmrcContent() {
+	return `@keystroke:registry=${getKeystrokeLocalNpmRegistryUrl()}\n`;
+}
+/** When the CLI cannot resolve `@keystroke/workflow-core` on disk (e.g. unusual installs). */
+const FALLBACK_WORKFLOW_CORE_VERSION_RANGE = "^0.0.1";
+/**
+* Semver range for scaffold `package.json` — uses the version of `@keystroke/workflow-core`
+* installed next to this CLI (same as the Keystroke toolchain the author runs).
+*/
+function workflowCoreScaffoldVersionRange() {
+	try {
+		const raw = readFileSync(createRequire(import.meta.url).resolve("@keystroke/workflow-core/package.json"), "utf-8");
+		const version = JSON.parse(raw).version?.trim();
+		if (version) return `^${version}`;
+	} catch {}
+	return FALLBACK_WORKFLOW_CORE_VERSION_RANGE;
+}
+/** When the CLI cannot resolve `@keystroke/skills` on disk. */
+const FALLBACK_SKILLS_VERSION_RANGE = "^0.0.1";
+/**
+* Semver range for scaffold `package.json` devDependency `@keystroke/skills` (published to local Verdaccio).
+*/
+function keystrokeSkillsScaffoldVersionRange() {
+	try {
+		const raw = readFileSync(createRequire(import.meta.url).resolve("@keystroke/skills/package.json"), "utf-8");
+		const version = JSON.parse(raw).version?.trim();
+		if (version) return `^${version}`;
+	} catch {}
+	return FALLBACK_SKILLS_VERSION_RANGE;
+}
+//#endregion
+//#region src/commands/init/agents-md.ts
+const AGENTS_FILENAME = "AGENTS.md";
+const AGENTS_BLURB_PACKAGE_PATH = "AGENTS-blurb.md";
+function normalizeLineEndings(value) {
+	return value.replace(/\r\n/g, "\n");
+}
+function normalizeBlurb(value) {
+	return `${normalizeLineEndings(value).trim()}\n`;
+}
+function resolveMonorepoSkillsBlurbPath() {
+	return fileURLToPath(new URL("../../../../../packages/skills/AGENTS-blurb.md", import.meta.url));
+}
+function resolveCliPackageSkillsBlurbPath() {
+	const relativePath = import.meta.url.includes("/dist/") ? "../AGENTS-blurb.md" : "../../../AGENTS-blurb.md";
+	return fileURLToPath(new URL(relativePath, import.meta.url));
+}
+function resolveBundledKeystrokeAgentsBlurbPath() {
+	const require = createRequire(import.meta.url);
+	try {
+		const skillsPackageJsonPath = require.resolve("@keystroke/skills/package.json");
+		return path$1.join(path$1.dirname(skillsPackageJsonPath), AGENTS_BLURB_PACKAGE_PATH);
+	} catch {}
+	try {
+		return resolveCliPackageSkillsBlurbPath();
+	} catch {}
+	return resolveMonorepoSkillsBlurbPath();
+}
+async function loadKeystrokeAgentsBlurb() {
+	try {
+		return normalizeBlurb(await readFile(resolveBundledKeystrokeAgentsBlurbPath(), "utf-8"));
+	} catch (error) {
+		throw new CliExitError("Could not load the bundled Keystroke AGENTS.md blurb. Reinstall the CLI or republish @keystrokehq/cli with AGENTS-blurb.md.", { cause: error });
+	}
+}
+async function ensureAgentsMarkdown(targetDir, blurb) {
+	const agentsFilePath = path$1.join(targetDir, AGENTS_FILENAME);
+	const normalizedBlurb = normalizeBlurb(blurb);
+	try {
+		const normalizedExisting = normalizeLineEndings(await readFile(agentsFilePath, "utf-8"));
+		if (normalizedExisting.includes(normalizedBlurb.trim())) return "skipped";
+		await writeFile(agentsFilePath, normalizedExisting.trim().length > 0 ? `${normalizedExisting.trimEnd()}\n\n${normalizedBlurb}` : normalizedBlurb, "utf-8");
+		return "updated";
+	} catch {
+		await writeFile(agentsFilePath, normalizedBlurb, "utf-8");
+		return "created";
+	}
+}
+//#endregion
+//#region src/commands/init/templates/biome-config.ts
+/**
+* Template for generating biome.json for a new Keystroke project.
+* Enables noProcessEnv and loads GritQL rules from @keystroke/workflow-core.
+*/
+function createBiomeConfigContent() {
+	return JSON.stringify({
+		$schema: "https://biomejs.dev/schemas/2.4.13/schema.json",
+		linter: {
+			enabled: true,
+			rules: { style: { noProcessEnv: "error" } }
+		},
+		plugins: ["./node_modules/@keystroke/workflow-core/biome/no-env-access.grit"]
+	}, null, 2);
+}
+//#endregion
+//#region src/commands/init/templates/env-example.ts
+/**
+* Template for generating a .env.example for a new Keystroke project.
+*/
+function createEnvExampleContent() {
+	return `# Keystroke credential environment variables (fallback when server credentials unavailable)
+# Naming convention: KEYSTROKE_<KEY>
+#
+# The Vitest plugin will first try to fetch credentials from the Keystroke server
+# (using your CLI auth). If that fails, it falls back to these env vars.
+#
+# Example for Slack credentialSet:
+# KEYSTROKE_SLACK_BOT_TOKEN=xoxb-...
+#
+# Example for Anthropic credentialSet:
+# KEYSTROKE_ANTHROPIC_API_KEY=sk-ant-...
+`;
+}
+//#endregion
+//#region src/commands/init/templates/gitignore.ts
+/**
+* Template for generating a .gitignore for a new Keystroke project.
+*/
+function createGitignoreContent() {
+	return `node_modules/
+dist/
+.env
+.env.local
+.env.test.local
+`;
+}
+//#endregion
+//#region src/commands/init/templates/hello-workflow.ts
+/**
+* Templates for generating an example workflow with steps for a new Keystroke project.
+*
+* Generates:
+*   workflows/hello/greet.step.ts      — Greet step
+*   workflows/hello/shout.step.ts      — Shout step
+*   workflows/hello/hello.workflow.ts  — Hello workflow composing both steps
+*   workflows/hello/hello.test.ts      — Smoke test for the sample workflow
+*/
+const HELLO_WORKFLOW_SCAFFOLD_FILES = {
+	greetStep: "workflows/hello/greet.step.ts",
+	shoutStep: "workflows/hello/shout.step.ts",
+	workflow: "workflows/hello/hello.workflow.ts",
+	test: "workflows/hello/hello.test.ts"
+};
+function createGreetStepContent() {
+	return `import { Step } from '@keystroke/workflow-core';
+import { z } from 'zod';
+
+export const greet = new Step({
+  id: 'greet',
+  name: 'Greet',
+  description: 'Creates a greeting message',
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+  run: async (input) => {
+    return { message: \`Hello, \${input.name}!\` };
+  },
+});
+`;
+}
+function createShoutStepContent() {
+	return `import { Step } from '@keystroke/workflow-core';
+import { z } from 'zod';
+
+export const shout = new Step({
+  id: 'shout',
+  name: 'Shout',
+  description: 'Converts text to uppercase',
+  input: z.object({ text: z.string() }),
+  output: z.object({ text: z.string() }),
+  run: async (input) => {
+    return { text: input.text.toUpperCase() };
+  },
+});
+`;
+}
+function createHelloWorkflowContent() {
+	return `import { Workflow } from '@keystroke/workflow-core';
+import { z } from 'zod';
+import { greet } from './greet.step';
+import { shout } from './shout.step';
+
+export const hello = new Workflow({
+  id: 'hello',
+  name: 'Hello',
+  description: 'A simple hello workflow that greets and shouts',
+  input: z.object({ name: z.string() }),
+  output: z.object({ text: z.string() }),
+  run: async (input) => {
+    const greeting = await greet.run(input);
+    const result = await shout.run({ text: greeting.message });
+    return result;
+  },
+});
+`;
+}
+function createHelloWorkflowTestContent() {
+	return `import { describe, expect, it } from 'vitest';
+import { hello } from './hello.workflow';
+
+describe('hello workflow', () => {
+  it('exports expected metadata', () => {
+    expect(hello.id).toBe('hello');
+    expect(hello.name).toBe('Hello');
+  });
+});
+`;
+}
+//#endregion
+//#region src/commands/init/templates/package-json.ts
+/**
+* Template for generating a package.json for a new Keystroke project.
+*
+* `@keystroke/workflow-core` uses a semver range; installs resolve via `.npmrc` → local Verdaccio
+* (see `pnpm publish:local` from the Keystroke monorepo).
+*/
+function createPackageJsonContent(projectName, options) {
+	return JSON.stringify({
+		name: projectName,
+		private: true,
+		type: "module",
+		scripts: {
+			test: "vitest run",
+			typecheck: "tsc --noEmit",
+			lint: "biome check ."
+		},
+		dependencies: {
+			"@keystroke/workflow-core": options.workflowCoreVersionRange,
+			zod: "^4.3.6"
+		},
+		devDependencies: {
+			"@keystroke/skills": options.skillsVersionRange,
+			"@biomejs/biome": "2.4.13",
+			vitest: "^4.0.18",
+			typescript: "^5.9.3"
+		}
+	}, null, 2);
+}
+//#endregion
+//#region src/commands/init/templates/tsconfig.ts
+/**
+* Template for generating a tsconfig.json for a new Keystroke project.
+*/
+function createTsconfigContent() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ES2022",
+			lib: ["ES2022"],
+			module: "ESNext",
+			moduleResolution: "bundler",
+			strict: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+			forceConsistentCasingInFileNames: true,
+			resolveJsonModule: true,
+			isolatedModules: true,
+			noUncheckedIndexedAccess: true,
+			noEmit: true
+		},
+		include: ["**/*.ts"],
+		exclude: ["node_modules", "dist"]
+	}, null, 2);
+}
+//#endregion
+//#region src/commands/init/templates/vitest-config.ts
+/**
+* Template for generating a vitest.config.ts for a new Keystroke project.
+*/
+function createVitestConfigContent() {
+	return `import { defineConfig } from 'vitest/config';
+import { keystrokeTestPlugin } from '@keystroke/workflow-core/vitest';
+
+export default defineConfig({
+  plugins: [keystrokeTestPlugin()],
+  test: {
+    include: ['**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});
+`;
+}
+//#endregion
+//#region src/commands/init/templates/vscode-extensions.ts
+/**
+* Template for generating .vscode/extensions.json recommending the Biome extension.
+*/
+function createVscodeExtensionsContent() {
+	return JSON.stringify({ recommendations: ["biomejs.biome"] }, null, 2);
+}
+//#endregion
+//#region src/commands/init/init.handler.ts
+function hasCliDescriptionOption(options) {
+	return options.description !== void 0;
+}
+async function promptProjectName(options, defaultName) {
+	const cliName = options.name;
+	if (cliName !== void 0 && cliName.trim().length > 0) return cliName.trim();
+	if (!process.stdin.isTTY) return defaultName.trim() || "project";
+	const answer = await text({
+		message: "Project name",
+		initialValue: defaultName.trim() || "project",
+		validate: (value) => {
+			if (!value?.trim()) return "Name is required";
+		}
+	});
+	if (isCancel(answer)) {
+		cancel("Init cancelled.");
+		throw new CliExitError("Init cancelled.", {
+			exitCode: 0,
+			reported: true
+		});
+	}
+	return answer.trim();
+}
+async function promptProjectDescription(options) {
+	if (hasCliDescriptionOption(options)) {
+		const t = options.description?.trim();
+		return t && t.length > 0 ? t : void 0;
+	}
+	if (!process.stdin.isTTY) return;
+	const answer = await text({
+		message: "Project description (optional)",
+		placeholder: "Shown in the Keystroke dashboard"
+	});
+	if (isCancel(answer)) {
+		cancel("Init cancelled.");
+		throw new CliExitError("Init cancelled.", {
+			exitCode: 0,
+			reported: true
+		});
+	}
+	const t = typeof answer === "string" ? answer.trim() : "";
+	return t.length > 0 ? t : void 0;
+}
+async function ensureScaffoldPackageJson(targetDir, projectName, ranges) {
+	const pkgPath = path.join(targetDir, "package.json");
+	try {
+		const raw = await readFile(pkgPath, "utf-8");
+		const pkg = JSON.parse(raw);
+		pkg.dependencies = pkg.dependencies ?? {};
+		pkg.dependencies["@keystroke/workflow-core"] = ranges.workflowCore;
+		pkg.dependencies.zod = pkg.dependencies.zod ?? "^4.3.6";
+		pkg.devDependencies = pkg.devDependencies ?? {};
+		pkg.devDependencies["@keystroke/skills"] = ranges.skills;
+		pkg.devDependencies.vitest = pkg.devDependencies.vitest ?? "^4.0.18";
+		pkg.devDependencies.typescript = pkg.devDependencies.typescript ?? "^5.9.3";
+		if (!pkg.name) pkg.name = projectName;
+		await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+		return "updated";
+	} catch {
+		await writeFile(pkgPath, `${createPackageJsonContent(projectName, {
+			workflowCoreVersionRange: ranges.workflowCore,
+			skillsVersionRange: ranges.skills
+		})}\n`, "utf-8");
+		return "created";
+	}
+}
+/** Ensure `.npmrc` sends `@keystroke/*` to the local Verdaccio registry. */
+async function ensureKeystrokeLocalRegistryNpmrc(targetDir) {
+	const npmrcPath = path.join(targetDir, ".npmrc");
+	const line = createKeystrokeLocalRegistryNpmrcContent().trimEnd();
+	try {
+		const existing = await readFile(npmrcPath, "utf-8");
+		if (existing.split(/\r?\n/).some((l) => l.trim().startsWith("@keystroke:registry="))) return "skipped";
+		await writeFile(npmrcPath, existing.trimEnd().length > 0 ? `${existing.trimEnd()}\n${line}\n` : `${line}\n`, "utf-8");
+		return "updated";
+	} catch {
+		await writeFile(npmrcPath, createKeystrokeLocalRegistryNpmrcContent(), "utf-8");
+		return "created";
+	}
+}
+async function handleInit(options, ctx) {
+	const targetDir = path.resolve(options.path ?? process.cwd());
+	const client = requireClient(ctx);
+	const configPath = getProjectConfigPath(targetDir);
+	const configFileName = path.basename(configPath);
+	let alreadyExists = false;
+	try {
+		await access(configPath);
+		alreadyExists = true;
+	} catch {}
+	const existing = await readProjectConfig(targetDir);
+	if (alreadyExists && !existing) throw new CliExitError(`${configFileName} exists but is invalid or uses an unsupported legacy shape. Migrate it before running \`keystroke init\`.`);
+	const needsRemoteProject = !existing?.organizationId || !existing?.projectId;
+	const projectName = await promptProjectName(options, existing?.name?.trim() || path.basename(targetDir));
+	let projectDescription;
+	if (needsRemoteProject) projectDescription = await promptProjectDescription(options);
+	const existingOrganizationId = existing?.organizationId;
+	const existingProjectId = existing?.projectId;
+	let organizationId = existingOrganizationId;
+	let projectId = existingProjectId;
+	if (!organizationId || !projectId) {
+		const auth = await client.public.auth.validate();
+		const res = await client.projects.create({
+			name: projectName,
+			description: projectDescription ?? null,
+			isDefault: false,
+			skipRepoCreation: true
+		});
+		organizationId = auth.organizationId;
+		projectId = res.project.id;
+	}
+	if (alreadyExists) {
+		ui.warn(`${configFileName} already exists in ${targetDir}`);
+		ui.hint("Updating name and tracking.");
+	} else {
+		await mkdir(targetDir, { recursive: true });
+		ui.success(`Created ${configFileName} in ${targetDir}`);
+	}
+	const descriptionForConfig = needsRemoteProject && projectDescription !== void 0 && projectDescription.length > 0 ? projectDescription : existing?.description;
+	await writeProjectConfig(targetDir, {
+		name: projectName,
+		organizationId,
+		projectId,
+		...descriptionForConfig && descriptionForConfig.length > 0 ? { description: descriptionForConfig } : {}
+	});
+	ui.hint(`Project "${projectName}" is now tracked.`);
+	ui.hint(`Project ID: ${projectId}`);
+	await trackProject(targetDir, { name: projectName });
+	const agentsAction = await ensureAgentsMarkdown(targetDir, await loadKeystrokeAgentsBlurb());
+	if (agentsAction === "created") ui.success("Created AGENTS.md with Keystroke project guidance.");
+	else if (agentsAction === "updated") ui.success("Updated AGENTS.md with Keystroke project guidance.");
+	if (options.scaffold) await scaffoldProject(targetDir, projectName, workflowCoreScaffoldVersionRange(), keystrokeSkillsScaffoldVersionRange(), options.install);
+}
+/** Write a file only if it does not already exist. Returns true if written. */
+async function writeIfMissing(filePath, content) {
+	try {
+		await access(filePath);
+		return false;
+	} catch {
+		await writeFile(filePath, content, "utf-8");
+		return true;
+	}
+}
+/**
+* Detect package manager from lockfiles. New projects (no lockfile) default to **pnpm** so `keystroke init`
+* matches the Keystroke monorepo toolchain.
+*/
+function detectPackageManager(targetDir) {
+	try {
+		accessSync(path.join(targetDir, "pnpm-lock.yaml"));
+		return "pnpm";
+	} catch {}
+	try {
+		accessSync(path.join(targetDir, "yarn.lock"));
+		return "yarn";
+	} catch {}
+	try {
+		accessSync(path.join(targetDir, "package-lock.json"));
+		return "npm";
+	} catch {}
+	return "pnpm";
+}
+/** Run install in targetDir. Returns true if succeeded. */
+function runInstall(targetDir) {
+	const pm = detectPackageManager(targetDir);
+	const [cmd, ...args] = pm === "pnpm" ? ["pnpm", "install"] : pm === "yarn" ? ["yarn", "install"] : ["npm", "install"];
+	return new Promise((resolve) => {
+		spawn(cmd, args, {
+			cwd: targetDir,
+			stdio: "inherit",
+			shell: true
+		}).on("close", (code) => resolve(code === 0));
+	});
+}
+async function trySyncAgentSkillsAfterScaffold(targetDir) {
+	const syncResult = await syncKeystrokeAgentSkills(targetDir);
+	if (syncResult.ok) ui.success(`Synced ${syncResult.copied.length} skill(s) to .cursor/skills and .claude/skills: ${syncResult.copied.join(", ")}`);
+	else if (syncResult.reason === "not_installed") ui.hint("After install completes, run `keystroke skills sync` to copy @keystroke/skills for Cursor / Claude Code.");
+	else ui.warn(`@keystroke/skills is installed at ${syncResult.packageRoot} but no skill directories with SKILL.md were found.`);
+}
+async function scaffoldProject(targetDir, projectName, workflowCoreVersionRange, skillsVersionRange, runInstallAfterScaffold) {
+	const pkgAction = await ensureScaffoldPackageJson(targetDir, projectName, {
+		workflowCore: workflowCoreVersionRange,
+		skills: skillsVersionRange
+	});
+	ui.success(pkgAction === "created" ? `Created package.json (@keystroke/workflow-core ${workflowCoreVersionRange}, @keystroke/skills ${skillsVersionRange})` : `Updated package.json (Keystroke deps → workflow-core ${workflowCoreVersionRange}, skills ${skillsVersionRange})`);
+	const registryUrl = getKeystrokeLocalNpmRegistryUrl();
+	const npmrcAction = await ensureKeystrokeLocalRegistryNpmrc(targetDir);
+	if (npmrcAction === "created") ui.success(`Created .npmrc (@keystroke → local registry ${registryUrl.trim()})`);
+	else if (npmrcAction === "updated") ui.success("Updated .npmrc with @keystroke registry line");
+	ui.hint("Before install: run Verdaccio (e.g. pnpm dlx verdaccio), then from the Keystroke repo: pnpm publish:local");
+	const files = [
+		{
+			rel: "vitest.config.ts",
+			content: createVitestConfigContent()
+		},
+		{
+			rel: "tsconfig.json",
+			content: createTsconfigContent()
+		},
+		{
+			rel: "biome.json",
+			content: createBiomeConfigContent()
+		},
+		{
+			rel: ".vscode/extensions.json",
+			content: createVscodeExtensionsContent()
+		},
+		{
+			rel: ".env.example",
+			content: createEnvExampleContent()
+		},
+		{
+			rel: ".gitignore",
+			content: createGitignoreContent()
+		},
+		{
+			rel: HELLO_WORKFLOW_SCAFFOLD_FILES.greetStep,
+			content: createGreetStepContent()
+		},
+		{
+			rel: HELLO_WORKFLOW_SCAFFOLD_FILES.shoutStep,
+			content: createShoutStepContent()
+		},
+		{
+			rel: HELLO_WORKFLOW_SCAFFOLD_FILES.workflow,
+			content: createHelloWorkflowContent()
+		},
+		{
+			rel: HELLO_WORKFLOW_SCAFFOLD_FILES.test,
+			content: createHelloWorkflowTestContent()
+		}
+	];
+	const created = [];
+	for (const { rel, content } of files) {
+		const filePath = path.join(targetDir, rel);
+		await mkdir(path.dirname(filePath), { recursive: true });
+		if (await writeIfMissing(filePath, content)) created.push(rel);
+	}
+	if (created.length > 0) ui.success(`Scaffolded ${created.length} file(s): ${created.join(", ")}`);
+	else ui.hint("Scaffold files already exist — skipped (package.json was still updated).");
+	if (runInstallAfterScaffold) {
+		const pkgJsonPath = path.join(targetDir, "package.json");
+		try {
+			await access(pkgJsonPath);
+		} catch {
+			return;
+		}
+		ui.hint("Running install...");
+		const ok = await runInstall(targetDir);
+		const pm = detectPackageManager(targetDir);
+		const testCmd = pm === "pnpm" ? "pnpm test" : pm === "yarn" ? "yarn test" : "npm test";
+		if (ok) {
+			ui.success("Dependencies installed.");
+			await trySyncAgentSkillsAfterScaffold(targetDir);
+			ui.hint(`Run \`${testCmd}\` to run tests.`);
+		} else {
+			ui.warn("Install failed. Run your package manager install manually.");
+			await trySyncAgentSkillsAfterScaffold(targetDir);
+		}
+	} else {
+		ui.hint("Run `pnpm install`, then `pnpm test` to run tests (or use your lockfile’s package manager).");
+		await trySyncAgentSkillsAfterScaffold(targetDir);
+	}
+}
+//#endregion
+export { handleInit };