Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/cli/src/commands/add/hook.ts
T

118 lines
3.8 KiB
TypeScript

/**
* `toolctrl add hook <name>` — 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<ScaffoldResult> {
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> | 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<void> {
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);
}
},
});