@spexcode/spec-cli 0.6.5

package/dist/guidance-catalog.d.ts

@@ -0,0 +1,64 @@
+export declare const GUIDANCE_SCHEMA_VERSION: 1;
+export declare const GUIDANCE_CATALOG_SCHEMA: "spexcode.guidance-catalog/v1";
+export declare const GUIDANCE_PAYLOAD_NAME: "guidance-catalog.json";
+export type GuidanceKind = 'plugin' | 'help' | 'guide';
+export type GuidanceSurface = 'system' | 'command' | 'hook' | 'skill' | 'agent' | 'review';
+export type GuidanceContentRole = 'prompt' | 'help' | 'guide' | 'signal';
+export type GuidanceSource = Readonly<{
+    path: string;
+    contentHash: string;
+    revision: string;
+}>;
+export type GuidanceEntry = Readonly<{
+    id: string;
+    kind: GuidanceKind;
+    surface?: GuidanceSurface;
+    title: string;
+    description: string;
+    contentRole: GuidanceContentRole;
+    content: string;
+    source: GuidanceSource;
+    runtime?: Readonly<{
+        path: string;
+        revision: string;
+        events: readonly string[];
+        order: number;
+        block: boolean;
+    }>;
+}>;
+export type EffectiveSystemContract = Readonly<{
+    content: string;
+    contentHash: string;
+    sourceEntryIds: readonly string[];
+}>;
+export type GuidanceBundle = Readonly<{
+    schemaVersion: typeof GUIDANCE_SCHEMA_VERSION;
+    revision: string;
+    entries: readonly GuidanceEntry[];
+    bundleHash: string;
+    catalogSchema: typeof GUIDANCE_CATALOG_SCHEMA;
+    payloadName: typeof GUIDANCE_PAYLOAD_NAME;
+    sourceRevision: string;
+    effectiveSystemContract: EffectiveSystemContract;
+}>;
+type GitReader = (args: string[]) => string;
+export type GuidanceCatalogOptions = Readonly<{
+    root?: string;
+    revision?: string;
+    sourceRevision?: (path: string) => string;
+    gitReader?: GitReader;
+}>;
+/**
+ * Immutable product-side projection over the authoritative plugin/help/guide surfaces.
+ * The constructor reads existing registries and materializes one export payload at call time.
+ */
+export declare class GuidanceCatalog {
+    readonly bundle: GuidanceBundle;
+    constructor(options?: GuidanceCatalogOptions);
+    entries(): readonly GuidanceEntry[];
+    toJSON(): GuidanceBundle;
+    exportJson(): string;
+    write(path: string): void;
+}
+export declare function buildGuidanceCatalog(options?: GuidanceCatalogOptions): GuidanceCatalog;
+export {};

package/dist/guidance-catalog.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { git, repoRoot } from '@spexcode/spec-core';
+import { loadAgentConfig, loadConfig, loadHookConfig, loadReviewConfig, loadSkillConfig, loadSystemConfig, } from '@spexcode/spec-core';
+import { helpCatalogEntries } from './help.js';
+import { guideCatalogEntries } from './guide.js';
+import { HookPromptCatalog, HOOK_PROMPT_SOURCE } from './hook-prompts.js';
+export const GUIDANCE_SCHEMA_VERSION = 1;
+export const GUIDANCE_CATALOG_SCHEMA = 'spexcode.guidance-catalog/v1';
+export const GUIDANCE_PAYLOAD_NAME = 'guidance-catalog.json';
+const SURFACES = [
+    ['agent', loadAgentConfig],
+    ['command', loadConfig],
+    ['hook', loadHookConfig],
+    ['review', loadReviewConfig],
+    ['skill', loadSkillConfig],
+    ['system', loadSystemConfig],
+];
+const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+function freeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        freeze(child);
+    return Object.freeze(value);
+}
+function sourcePathForPreset(preset) {
+    return join(preset.dir, 'spec.md').replaceAll('\\', '/');
+}
+function sortEntries(entries) {
+    return entries.sort((a, b) => {
+        const left = `${a.kind}\0${a.id}\0${a.surface ?? ''}\0${a.source.path}`;
+        const right = `${b.kind}\0${b.id}\0${b.surface ?? ''}\0${b.source.path}`;
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+}
+function sourceRevision(root, path, readGit) {
+    const result = readGit(['-C', root, 'log', '-1', '--format=%H', '--', path]).trim();
+    return result || 'working-tree';
+}
+function currentRevision(root, readGit) {
+    return readGit(['-C', root, 'rev-parse', 'HEAD']).trim() || 'working-tree';
+}
+function entrySource(root, path, text, revision, readSourceRevision) {
+    return { path: relative(root, join(root, path)).replaceAll('\\', '/'), contentHash: sha256(text), revision: readSourceRevision(path) || revision };
+}
+/**
+ * Immutable product-side projection over the authoritative plugin/help/guide surfaces.
+ * The constructor reads existing registries and materializes one export payload at call time.
+ */
+export class GuidanceCatalog {
+    bundle;
+    constructor(options = {}) {
+        const root = options.root ?? repoRoot();
+        const readGit = options.gitReader ?? git;
+        const revision = options.revision ?? currentRevision(root, readGit);
+        const readSourceRevision = options.sourceRevision ?? ((path) => sourceRevision(root, path, readGit));
+        const sourceRevisions = new Map();
+        const sourceRevisionFor = (path) => {
+            const known = sourceRevisions.get(path);
+            if (known)
+                return known;
+            const value = readSourceRevision(path) || revision;
+            sourceRevisions.set(path, value);
+            return value;
+        };
+        const entries = [];
+        const hookPrompts = new HookPromptCatalog();
+        for (const [surface, loader] of SURFACES) {
+            for (const preset of loader()) {
+                if (surface === 'hook') {
+                    const prompt = hookPrompts.entry(preset.name);
+                    const handler = preset.files.find((file) => file.endsWith('.sh'));
+                    if (!handler)
+                        throw new Error(`surface:hook node '${preset.name}' ships no .sh script (one co-located .sh required)`);
+                    entries.push({
+                        id: `plugin:${surface}:${preset.name}`,
+                        kind: 'plugin',
+                        surface,
+                        title: prompt.title,
+                        description: prompt.description,
+                        contentRole: prompt.role,
+                        content: prompt.content,
+                        source: entrySource(root, HOOK_PROMPT_SOURCE, prompt.content, revision, sourceRevisionFor),
+                        runtime: {
+                            path: handler,
+                            revision: sourceRevisionFor(handler),
+                            events: [...preset.events],
+                            order: preset.order,
+                            block: preset.block,
+                        },
+                    });
+                    continue;
+                }
+                const path = sourcePathForPreset(preset);
+                entries.push({
+                    id: `plugin:${surface}:${preset.name}`,
+                    kind: 'plugin',
+                    surface,
+                    title: preset.title,
+                    description: preset.desc,
+                    contentRole: 'prompt',
+                    content: preset.body,
+                    source: entrySource(root, path, preset.body, revision, sourceRevisionFor),
+                });
+            }
+        }
+        for (const entry of helpCatalogEntries()) {
+            const path = 'spec-cli/src/help.ts';
+            entries.push({
+                id: `help:${entry.id}`,
+                kind: 'help',
+                title: entry.title,
+                description: 'CLI command usage and safety guidance',
+                contentRole: 'help',
+                content: entry.text,
+                source: entrySource(root, path, entry.text, revision, sourceRevisionFor),
+            });
+        }
+        for (const entry of guideCatalogEntries()) {
+            const path = 'spec-cli/src/guide.ts';
+            entries.push({
+                id: `guide:${entry.id}`,
+                kind: 'guide',
+                title: entry.title,
+                description: 'CLI workflow and format guidance',
+                contentRole: 'guide',
+                content: entry.text,
+                source: entrySource(root, path, entry.text, revision, sourceRevisionFor),
+            });
+        }
+        const systemEntries = entries.filter((entry) => entry.kind === 'plugin' && entry.surface === 'system');
+        const effectiveSystemContent = systemEntries.map((entry) => entry.content.trim()).filter(Boolean).join('\n\n');
+        const payload = {
+            schemaVersion: GUIDANCE_SCHEMA_VERSION,
+            revision,
+            entries: sortEntries(entries),
+            catalogSchema: GUIDANCE_CATALOG_SCHEMA,
+            payloadName: GUIDANCE_PAYLOAD_NAME,
+            sourceRevision: revision,
+            effectiveSystemContract: {
+                content: effectiveSystemContent,
+                contentHash: sha256(effectiveSystemContent),
+                sourceEntryIds: systemEntries.map((entry) => entry.id),
+            },
+        };
+        const bundleHash = sha256(JSON.stringify(payload));
+        this.bundle = freeze({ ...payload, bundleHash });
+    }
+    entries() {
+        return this.bundle.entries;
+    }
+    toJSON() {
+        return this.bundle;
+    }
+    exportJson() {
+        return `${JSON.stringify(this.bundle, null, 2)}\n`;
+    }
+    write(path) {
+        writeFileSync(path, this.exportJson(), 'utf8');
+    }
+}
+export function buildGuidanceCatalog(options = {}) {
+    return new GuidanceCatalog(options);
+}

package/dist/guide.d.ts

@@ -0,0 +1,8 @@
+export declare function guideText(topic?: string): string | null;
+export declare function guideTopics(): string[];
+export type GuideCatalogEntry = Readonly<{
+    id: string;
+    title: string;
+    text: string;
+}>;
+export declare function guideCatalogEntries(): readonly GuideCatalogEntry[];