@funnelsgrove/cli 0.1.14 → 0.1.18

package/dist/diagnosticOutput.d.ts

@@ -0,0 +1,42 @@
+export type FunnelValidationExitCode = 0 | 1 | 2;
+export type FunnelValidationDiagnostic = {
+    code: string;
+    severity: 'error';
+    file: string | null;
+    stepId: string | null;
+    expected?: unknown;
+    received?: unknown;
+    reason: string;
+    guide: string;
+    repair: string;
+};
+export type FunnelValidationResult = {
+    schemaVersion: 1;
+    contractVersion: number;
+    valid: boolean;
+    diagnostics: readonly FunnelValidationDiagnostic[];
+    exitCode: FunnelValidationExitCode;
+};
+export type ValidationOutputInput = {
+    command: string;
+    result: FunnelValidationResult;
+};
+export type FunnelValidationOutput = {
+    schemaVersion: 1;
+    command: string;
+    contractVersion: number;
+    valid: boolean;
+    diagnostics: readonly FunnelValidationDiagnostic[];
+    exitCode: FunnelValidationExitCode;
+};
+export type ValidationDiagnosticInput = Omit<FunnelValidationDiagnostic, 'severity' | 'file' | 'stepId' | 'expected' | 'received'> & {
+    file?: string | null;
+    stepId?: string | null;
+    expected: unknown;
+    received: unknown;
+};
+export declare const createValidationDiagnostic: (input: ValidationDiagnosticInput) => FunnelValidationDiagnostic;
+export declare const isValidationDiagnostic: (value: unknown) => value is FunnelValidationDiagnostic;
+export declare const buildValidationOutput: (input: ValidationOutputInput) => FunnelValidationOutput;
+export declare const renderValidationJson: (input: ValidationOutputInput) => string;
+export declare const renderValidationHuman: (input: ValidationOutputInput) => string;

package/dist/diagnosticOutput.js

@@ -0,0 +1,83 @@
+const DIAGNOSTIC_KEYS = [
+    'code',
+    'severity',
+    'file',
+    'stepId',
+    'expected',
+    'received',
+    'reason',
+    'guide',
+    'repair',
+];
+const REQUIRED_DIAGNOSTIC_KEYS = [
+    'code',
+    'severity',
+    'file',
+    'stepId',
+    'reason',
+    'guide',
+    'repair',
+];
+export const createValidationDiagnostic = (input) => ({
+    code: input.code,
+    severity: 'error',
+    file: input.file ?? null,
+    stepId: input.stepId ?? null,
+    expected: input.expected,
+    received: input.received,
+    reason: input.reason,
+    guide: input.guide,
+    repair: input.repair,
+});
+export const isValidationDiagnostic = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const diagnostic = value;
+    if (Object.keys(diagnostic).some((key) => !DIAGNOSTIC_KEYS.includes(key))
+        || REQUIRED_DIAGNOSTIC_KEYS.some((key) => !(key in diagnostic)))
+        return false;
+    return typeof diagnostic.code === 'string'
+        && /^FG-[A-Z]+-\d{3}$/.test(diagnostic.code)
+        && diagnostic.severity === 'error'
+        && (diagnostic.file === null || typeof diagnostic.file === 'string')
+        && (diagnostic.stepId === null || typeof diagnostic.stepId === 'string')
+        && typeof diagnostic.reason === 'string'
+        && typeof diagnostic.guide === 'string'
+        && typeof diagnostic.repair === 'string';
+};
+export const buildValidationOutput = (input) => ({
+    schemaVersion: 1,
+    command: input.command,
+    contractVersion: input.result.contractVersion,
+    valid: input.result.valid,
+    diagnostics: input.result.diagnostics,
+    exitCode: input.result.exitCode,
+});
+export const renderValidationJson = (input) => `${JSON.stringify(buildValidationOutput(input), null, 2)}\n`;
+const renderValue = (value) => {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return '[unserializable]';
+    }
+};
+const renderDiagnostic = (diagnostic) => [
+    `[${diagnostic.code}] ${diagnostic.reason}`,
+    ...(diagnostic.file === null ? [] : [`  File: ${diagnostic.file}`]),
+    ...(diagnostic.stepId === null ? [] : [`  Step: ${diagnostic.stepId}`]),
+    `  Expected: ${renderValue(diagnostic.expected)}`,
+    `  Received: ${renderValue(diagnostic.received)}`,
+    `  Repair: ${diagnostic.repair}`,
+    `  Guide: ${diagnostic.guide}`,
+].join('\n');
+export const renderValidationHuman = (input) => {
+    const summary = input.result.exitCode === 0
+        ? 'valid'
+        : input.result.exitCode === 1 ? 'blocked' : 'error';
+    const lines = [
+        `Funnel validation: ${summary} (contract ${input.result.contractVersion})`,
+        ...input.result.diagnostics.map(renderDiagnostic),
+    ];
+    return `${lines.join('\n')}\n`;
+};

package/dist/docsOutput.d.ts

@@ -0,0 +1,19 @@
+import type { DocsDiagnostic, DocsFileStatus, DocsStatus } from './docsTransaction.js';
+export type DocsExitCode = 0 | 1 | 2 | 3 | 4;
+export type DocsHumanMode = 'status' | 'diff';
+export type DocsOutputInput = {
+    command: string;
+    status: DocsStatus;
+    exitCode: DocsExitCode;
+};
+export type DocsOutput = {
+    schemaVersion: 1;
+    command: string;
+    status: DocsStatus;
+    actions: DocsFileStatus[];
+    diagnostics: DocsDiagnostic[];
+    exitCode: DocsExitCode;
+};
+export declare const buildDocsOutput: (input: DocsOutputInput) => DocsOutput;
+export declare const renderDocsJson: (input: DocsOutputInput) => string;
+export declare const renderDocsHuman: (input: DocsOutputInput, mode?: DocsHumanMode) => string;

package/dist/docsOutput.js

@@ -0,0 +1,73 @@
+const compareText = (left, right) => {
+    const normalizedLeft = left ?? '';
+    const normalizedRight = right ?? '';
+    return normalizedLeft < normalizedRight ? -1 : normalizedLeft > normalizedRight ? 1 : 0;
+};
+const compareFiles = (left, right) => compareText(left.path, right.path)
+    || compareText(left.action, right.action)
+    || compareText(left.state, right.state)
+    || compareText(left.currentHash, right.currentHash)
+    || compareText(left.bundledHash, right.bundledHash)
+    || compareText(left.priorHash, right.priorHash);
+const compareDiagnostics = (left, right) => compareText(left.code, right.code)
+    || compareText(left.path, right.path)
+    || compareText(left.message, right.message);
+const normalizeFile = (file) => ({
+    path: file.path,
+    state: file.state,
+    action: file.action,
+    ...(file.currentHash === undefined ? {} : { currentHash: file.currentHash }),
+    ...(file.bundledHash === undefined ? {} : { bundledHash: file.bundledHash }),
+    ...(file.priorHash === undefined ? {} : { priorHash: file.priorHash }),
+});
+const normalizeDiagnostic = (diagnostic) => ({
+    code: diagnostic.code,
+    ...(diagnostic.path === undefined ? {} : { path: diagnostic.path }),
+    message: diagnostic.message,
+});
+const normalizeStatus = (status) => ({
+    bundleVersion: status.bundleVersion,
+    contractVersion: status.contractVersion,
+    clean: status.clean,
+    files: status.files.map(normalizeFile).sort(compareFiles),
+    diagnostics: status.diagnostics.map(normalizeDiagnostic).sort(compareDiagnostics),
+});
+export const buildDocsOutput = (input) => {
+    const status = normalizeStatus(input.status);
+    return {
+        schemaVersion: 1,
+        command: input.command,
+        status,
+        actions: status.files.filter((file) => file.action !== 'none'),
+        diagnostics: status.diagnostics,
+        exitCode: input.exitCode,
+    };
+};
+export const renderDocsJson = (input) => `${JSON.stringify(buildDocsOutput(input), null, 2)}\n`;
+const renderDiagnostic = (diagnostic) => [
+    diagnostic.code,
+    diagnostic.path,
+    diagnostic.message,
+].filter((part) => part !== undefined).join('\t');
+const renderSummary = (label, status) => `${label}: ${status.clean ? 'clean' : 'drift'} (bundle ${status.bundleVersion}, contract ${status.contractVersion})`;
+const hashBefore = (file) => file.currentHash ?? file.priorHash ?? '-';
+const hashAfter = (file) => file.action === 'retire-known' || file.action === 'retire-owned'
+    ? '-'
+    : file.bundledHash ?? '-';
+export const renderDocsHuman = (input, mode = 'status') => {
+    const output = buildDocsOutput(input);
+    const files = mode === 'diff' ? output.actions : output.status.files;
+    const lines = [
+        renderSummary(mode === 'diff' ? 'Funnel docs diff' : 'Funnel docs', output.status),
+        ...files.map((file) => mode === 'diff'
+            ? [
+                file.action,
+                file.path,
+                file.state,
+                `${hashBefore(file)} -> ${hashAfter(file)}`,
+            ].join('\t')
+            : [file.action, file.path, file.state].join('\t')),
+        ...output.diagnostics.map(renderDiagnostic),
+    ];
+    return `${lines.join('\n')}\n`;
+};

package/dist/docsTransaction.d.ts

@@ -0,0 +1,81 @@
+export declare const DOCS_MANIFEST_FILE = ".funnelsgrove-docs.json";
+export type FunnelDocsManifest = {
+    schemaVersion: 1;
+    bundleVersion: string;
+    stepContractVersion: number;
+    contractHash: string;
+    managedFiles: Array<{
+        path: string;
+        sha256: string;
+    }>;
+};
+export type LegacyDocsCatalogEntry = {
+    version: string;
+    path: string;
+    sha256: string;
+};
+export type DocsFileState = 'current' | 'missing' | 'changed' | 'known-legacy-current-path' | 'known-legacy-obsolete' | 'owned-obsolete' | 'conflict';
+export type DocsAction = 'none' | 'install' | 'adopt' | 'replace-known' | 'retire-known' | 'retire-owned' | 'conflict';
+export type DocsDiagnostic = {
+    code: string;
+    message: string;
+    path?: string;
+};
+export type Diagnostic = DocsDiagnostic;
+export type DocsFileStatus = {
+    path: string;
+    state: DocsFileState;
+    action: DocsAction;
+    currentHash?: string;
+    bundledHash?: string;
+    priorHash?: string;
+};
+export type DocsStatus = {
+    bundleVersion: string;
+    contractVersion: number;
+    clean: boolean;
+    files: DocsFileStatus[];
+    diagnostics: DocsDiagnostic[];
+};
+type BundledFile = {
+    bytes: Buffer;
+    mode: number;
+    path: string;
+    sha256: string;
+};
+export type BundledDocs = {
+    root: string;
+    manifest: FunnelDocsManifest;
+    manifestBytes: Buffer;
+    files: Map<string, BundledFile>;
+};
+type InspectedFile = Omit<DocsFileStatus, 'action'>;
+export type DocsInspection = {
+    bundle: BundledDocs;
+    targetRoot: string;
+    priorManifest: FunnelDocsManifest | null;
+    files: InspectedFile[];
+};
+export type DocsFaultPoint = {
+    operation: 'stage' | 'backup' | 'apply' | 'manifest' | 'residue';
+    timing: 'before' | 'after';
+    path: string;
+};
+export type DocsTransactionOptions = {
+    transactionId?: string;
+    faultInjector?: (point: DocsFaultPoint) => void | Promise<void>;
+    legacyCatalog?: readonly LegacyDocsCatalogEntry[];
+};
+export declare class DocsTransactionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const loadBundledDocs: (sourceDir: string) => Promise<BundledDocs>;
+export declare const inspectTemplateDocs: (bundle: BundledDocs, targetDir: string, options?: {
+    legacyCatalog?: readonly LegacyDocsCatalogEntry[];
+}) => Promise<DocsInspection>;
+export declare const planTemplateDocsUpdate: (inspection: DocsInspection) => DocsStatus;
+export declare const applyTemplateDocsUpdate: (bundle: BundledDocs, targetDir: string, status: DocsStatus, options?: DocsTransactionOptions) => Promise<void>;
+export declare const recoverTemplateDocs: (targetDir: string, options?: Pick<DocsTransactionOptions, "faultInjector">) => Promise<"none" | "completed" | "restored">;
+export declare const resolveTemplateDocsConflict: (bundle: BundledDocs, targetDir: string, relativePath: string, options?: DocsTransactionOptions) => Promise<void>;
+export {};