/** * `toolctrl add hook ` — scaffold a plugin-hook registration file. * * NOTE: the plugin-system itself (Phase 06) is not yet built. This * generator therefore produces a *stub* with a clear "scaffolding for * future plugin system" header so downstream readers know the API * surface is provisional. Once Phase 06 lands the template will be * upgraded to import the real `@toolctrl/plugin-sdk`. * * Refs: docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md * Refs: docs/improvement-plan/06-plugin-system/audit-docs.md */ import { defineCommand } from "citty"; import consola from "consola"; import path from "node:path"; import { camelCase, createScaffoldResult, pascalCase, resolveRepoRoot, validateIdentifier, writeScaffoldFile, type ScaffoldResult, } from "../_lib/scaffold.js"; export type GenerateHookOptions = { name: string; repoRoot?: string; dryRun?: boolean; }; export async function generateHook(options: GenerateHookOptions): Promise { const baseName = validateIdentifier(options.name, "hook name"); const dryRun = options.dryRun ?? false; const repoRoot = resolveRepoRoot(options.repoRoot); const camel = camelCase(baseName); const pascal = pascalCase(baseName); const result = createScaffoldResult(dryRun); const hookDir = path.join(repoRoot, "apps/web/app/hooks/_generated"); await writeScaffoldFile({ targetPath: path.join(hookDir, `${camel}.hook.ts`), contents: renderHookFile({ camel, pascal }), dryRun, result, }); result.notes.push( "Phase 06 plugin system is not implemented yet — this hook is a forward-compatible stub.", "Update the import path to @toolctrl/plugin-sdk once Phase 06 ships.", ); return result; } function renderHookFile({ camel, pascal }: { camel: string; pascal: string }): string { return `/** * Scaffolding for the future plugin-system (Phase 06). * * This file registers the "${camel}" hook. The current implementation * is a no-op because the plugin-runtime is not wired up yet — see * docs/improvement-plan/06-plugin-system/audit-docs.md for the planned * surface. Once the SDK lands, replace the body of \`register${pascal}Hook\` * with the real \`pluginRuntime.registerHook(…)\` call. */ export type ${pascal}HookPayload = { tenantId: string; // Add domain-specific payload fields before exposing this hook publicly. }; export type ${pascal}HookHandler = (payload: ${pascal}HookPayload) => Promise | void; const handlers: ${pascal}HookHandler[] = []; export function register${pascal}Hook(handler: ${pascal}HookHandler): () => void { handlers.push(handler); return () => { const idx = handlers.indexOf(handler); if (idx >= 0) handlers.splice(idx, 1); }; } export async function trigger${pascal}Hook(payload: ${pascal}HookPayload): Promise { for (const handler of handlers) { await handler(payload); } } `; } export const addHookCommand = defineCommand({ meta: { name: "hook", description: "Scaffold a plugin-hook registration file (Phase 06 forward-compat stub).", }, args: { name: { type: "positional", required: true, description: "Hook name (camel/kebab/pascal — normalised)." }, "dry-run": { type: "boolean", required: false, description: "Print the would-be writes without touching the filesystem.", }, }, async run({ args }) { const result = await generateHook({ name: args.name, dryRun: args["dry-run"] === true }); consola.success( `${result.dryRun ? "[dry-run] " : ""}Generated hook "${args.name}" — ${result.files.length} file(s).`, ); for (const file of result.files) { consola.info(` ${result.dryRun ? "would write" : "wrote"} ${file.path}`); } for (const note of result.notes) { consola.warn(note); } }, });