peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/audit-artifact-runners.js

@@ -0,0 +1,170 @@
+/**
+ * `peaks audit artifact` runners — first-class CLI surface for the 4 audit
+ * artifact types. Replaces the 2026-06-22 "hand `git add` into
+ * .peaks/memory/" anti-pattern that left 4 orphan files. Each kind routes to
+ * exactly one writer in artifact-writer.ts; the writer enforces canonical
+ * frontmatter, so the memory-shape guard never fires for new writes.
+ *
+ * The action body moved out of `audit-commands.ts` verbatim; the registrar now
+ * only wires the commands and delegates. Every envelope, error code and hint
+ * string is unchanged.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { writeDecision, writeMachineOutput, writeNarrative, writePrompt } from '../../services/audit/artifact-writer.js';
+import { parseRedLineAuditInput, RedLineAuditInputError } from '../../services/audit/red-line-audit-input.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { isSupportedArtifactKind, PROJECT_PATH_HINT, SUPPORTED_ARTIFACT_KINDS, validateProjectRoot } from './audit-command-shared.js';
+import { emptyArtifactWriteRecord } from './audit-refusal-data.js';
+export const ARTIFACT_GROUP_DESCRIPTION = 'Manage audit artifacts (decision / prompt / machine-output / narrative) under .peaks/memory/';
+export const ARTIFACT_WRITE_DESCRIPTION = 'Persist a single audit artifact to .peaks/memory/ via the artifact-writer (canonical frontmatter)';
+const INPUT_PATH_HINT = 'Verify the --input path is correct (relative paths resolve against cwd)';
+/** Length of the `YYYY-MM-DD` prefix of an ISO timestamp. */
+const ISO_DATE_LENGTH = 10;
+/**
+ * Names the unreachable `--kind` without tripping the template-expression rule:
+ * by the time the `default` arm runs, the narrowing has reduced `kind` to
+ * `never`, so the message is built from a `string` parameter instead.
+ */
+function unreachableKindError(kind) {
+    return new Error(`unreachable: kind=${kind}`);
+}
+function refuseArtifactWrite(refusal) {
+    printResult(refusal.io, fail('audit.artifact.write', refusal.code, refusal.message, emptyArtifactWriteRecord(refusal.kind), refusal.nextActions), refusal.json);
+    process.exitCode = 1;
+}
+function writeByKind(request) {
+    const writeOpts = {
+        projectRoot: request.projectRoot,
+        dryRun: request.dryRun,
+        ...(request.rid ? { rid: request.rid } : {})
+    };
+    switch (request.kind) {
+        case 'prompt': {
+            const body = readFileSync(request.inputAbs, 'utf8');
+            return writePrompt({ name: request.baseName, description: request.description, body }, writeOpts);
+        }
+        case 'machine-output': {
+            const json = readFileSync(request.inputAbs, 'utf8');
+            return writeMachineOutput({ name: request.baseName, description: request.description, json }, writeOpts);
+        }
+        case 'narrative': {
+            const body = readFileSync(request.inputAbs, 'utf8');
+            return writeNarrative({ name: request.baseName, description: request.description, body }, writeOpts);
+        }
+        case 'decision': {
+            // `--input` is a RedLineAudit JSON document — typically
+            // an archived `peaks audit static` result — validated field by field
+            // before it reaches the writer, because the writer renders whatever
+            // it is given into a memory record with no further checks.
+            // `--name` and `--description` do not apply: the decision slug and
+            // title come from the scan date (and `--rid`), exactly as
+            // `peaks audit static --record` derives them.
+            const audit = parseRedLineAuditInput(readFileSync(request.inputAbs, 'utf8'));
+            return writeDecision(audit, writeOpts);
+        }
+        default: {
+            // Unreachable: isSupportedArtifactKind already filtered.
+            throw unreachableKindError(request.kind);
+        }
+    }
+}
+function artifactWriteNextActions(record) {
+    return [
+        `Artifact written via ${record.kind} writer.`,
+        record.indexSynced
+            ? 'Memory index regenerated; entry will appear in `peaks project memories` on next read.'
+            : 'Memory index NOT regenerated; run `peaks project memories --project <root>` to refresh.'
+    ];
+}
+function persistArtifact(request) {
+    let record;
+    try {
+        record = writeByKind(request);
+    }
+    catch (err) {
+        // A malformed decision input is the caller's document, not a write
+        // failure: name it as input so the remedy reads as "fix the JSON field".
+        refuseArtifactWrite({
+            io: request.io,
+            json: request.json,
+            kind: request.kind,
+            code: err instanceof RedLineAuditInputError ? 'AUDIT_ARTIFACT_INPUT_INVALID' : 'WRITE_FAILED',
+            message: getErrorMessage(err),
+            nextActions: err instanceof RedLineAuditInputError
+                ? [
+                    'Inspect the named field; --kind decision takes the JSON shape `peaks audit static --json` prints.'
+                ]
+                : ['Inspect the error message; for --kind machine-output ensure --input is valid JSON']
+        });
+        return;
+    }
+    printResult(request.io, ok('audit.artifact.write', record, [], artifactWriteNextActions(record)), request.json);
+}
+/**
+ * The three refusals `--project`, `--kind` and `--input` can earn, in the
+ * order the original action checked them. Prints the envelope and sets the
+ * exit code on failure.
+ */
+function precheckArtifactWrite(options, io) {
+    const validation = validateProjectRoot(options.project);
+    if (!validation.ok) {
+        refuseArtifactWrite({
+            io,
+            json: options.json,
+            kind: 'narrative',
+            code: validation.code,
+            message: validation.message,
+            nextActions: [PROJECT_PATH_HINT]
+        });
+        return { ok: false };
+    }
+    if (!isSupportedArtifactKind(options.kind)) {
+        refuseArtifactWrite({
+            io,
+            json: options.json,
+            kind: 'narrative',
+            code: 'INVALID_KIND',
+            message: `Unknown --kind "${options.kind}". Supported: ${SUPPORTED_ARTIFACT_KINDS.join(', ')}.`,
+            nextActions: [
+                `Re-run with --kind <one of ${SUPPORTED_ARTIFACT_KINDS.join(' | ')}>`,
+                'See .peaks/memory/audit-artifact-convention.md for the 4 artifact types.'
+            ]
+        });
+        return { ok: false };
+    }
+    const inputAbs = resolve(options.input);
+    if (!existsSync(inputAbs)) {
+        refuseArtifactWrite({
+            io,
+            json: options.json,
+            kind: options.kind,
+            code: 'INPUT_NOT_FOUND',
+            message: `--input file not found: ${options.input}`,
+            nextActions: [INPUT_PATH_HINT]
+        });
+        return { ok: false };
+    }
+    return { ok: true, projectRoot: validation.projectRoot, kind: options.kind, inputAbs };
+}
+export function runArtifactWrite(options, io) {
+    const precheck = precheckArtifactWrite(options, io);
+    if (!precheck.ok) {
+        return;
+    }
+    const baseName = options.name ?? options.input.split(/[\\/]/).pop() ?? 'untitled';
+    const description = options.description ??
+        `Audit artifact (${precheck.kind}) archived via peaks audit artifact write on ${new Date().toISOString().slice(0, ISO_DATE_LENGTH)}.`;
+    persistArtifact({
+        io,
+        json: options.json,
+        kind: precheck.kind,
+        inputAbs: precheck.inputAbs,
+        baseName,
+        description,
+        projectRoot: precheck.projectRoot,
+        dryRun: options.dryRun === true,
+        ...(options.rid ? { rid: options.rid } : {})
+    });
+}

package/dist/cli/commands/audit-command-shared.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared plumbing for the `peaks audit *` command family.
+ *
+ * Split out of `audit-commands.ts` (file-size cap) so each runner module can
+ * read the option shapes, the `--project` validation and the two whitelists
+ * without importing the registrar back. Dependency direction is one-way:
+ * nothing here imports `audit-commands.ts`.
+ */
+import type { AuditGoalOutput } from '../../services/audit/audit-goal-types.js';
+import type { AgentShieldState } from '../../services/audit/static-service.js';
+import type { ArtifactKind } from '../../services/audit/artifact-writer.js';
+import type { AuditDecisionRecord } from '../../services/audit/decision-writer.js';
+import type { RedLineAudit } from '../../services/audit/types.js';
+export type RedLinesOptions = {
+    project: string;
+    json?: boolean;
+    noColor?: boolean;
+};
+export type StaticAuditOptions = {
+    project: string;
+    json?: boolean;
+    noColor?: boolean;
+    record?: boolean;
+    rid?: string;
+};
+export type AuditGoalOptions = {
+    project: string;
+    need: string;
+    llmProvider?: string;
+    json?: boolean;
+};
+export type ArtifactWriteOptions = {
+    project: string;
+    kind: string;
+    input: string;
+    description?: string;
+    name?: string;
+    rid?: string;
+    dryRun?: boolean;
+    json?: boolean;
+};
+export type ProseRatioOptions = {
+    project: string;
+    target: string;
+    json?: boolean;
+};
+export declare const SUPPORTED_ARTIFACT_KINDS: readonly ArtifactKind[];
+export declare function isSupportedArtifactKind(value: string): value is ArtifactKind;
+/** Whitelist of supported `--llm-provider` values for `peaks audit goal`. */
+export declare const SUPPORTED_LLM_PROVIDERS: readonly ["anthropic", "stub"];
+export type SupportedLlmProvider = (typeof SUPPORTED_LLM_PROVIDERS)[number];
+/**
+ * The real provider is the default: `peaks audit goal` is the entry gate for
+ * every peaks-* workflow, so it must audit by default and only scaffold when
+ * a caller explicitly asks for `stub`.
+ */
+export declare const DEFAULT_LLM_PROVIDER: SupportedLlmProvider;
+export declare function isSupportedLlmProvider(value: string): value is SupportedLlmProvider;
+/** The one hint every `--project` refusal carries, verbatim. */
+export declare const PROJECT_PATH_HINT = "Verify the project path exists and is a directory";
+/** The one hint every scanner-failure refusal carries, verbatim. */
+export declare const SCANNER_HINT = "Inspect scanner logs and re-run with the same --project path";
+/** `--project` is valid only when it resolves to an existing directory. */
+export type ProjectRootValidation = {
+    ok: true;
+    projectRoot: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare function validateProjectRoot(projectArg: string): ProjectRootValidation;
+/** `audit-failed` is a failure envelope's status — never a scaffold, never a success. */
+export type AuditGoalStatus = 'audit-complete' | 'scaffold-only' | 'audit-failed';
+export interface AuditGoalData {
+    readonly status: AuditGoalStatus;
+    /** Which LLM produced (or failed to produce) the audit. `unresolved` = rejected before binding. */
+    readonly providerBinding: 'anthropic-messages-api' | 'stub' | 'unresolved';
+    readonly need: string;
+    readonly projectRoot: string;
+    /** The validated 6-dimension audit. Present on success only. */
+    readonly result?: AuditGoalOutput;
+    /** The bound model. Present on a real run only. */
+    readonly model?: string;
+    /**
+     * Environment variables the binding needed and did not find. Present on a
+     * binding failure only, and verbatim: `fail()` redacts `message`, so this
+     * is the channel that reliably names what the operator must set.
+     */
+    readonly missingEnv?: readonly string[];
+}
+export interface StaticAuditData {
+    readonly audit: RedLineAudit;
+    readonly agentShield: AgentShieldState;
+    /** Populated only when `--record` is passed. Persisted decision record path. */
+    readonly decision?: AuditDecisionRecord;
+}

package/dist/cli/commands/audit-command-shared.js

@@ -0,0 +1,60 @@
+/**
+ * Shared plumbing for the `peaks audit *` command family.
+ *
+ * Split out of `audit-commands.ts` (file-size cap) so each runner module can
+ * read the option shapes, the `--project` validation and the two whitelists
+ * without importing the registrar back. Dependency direction is one-way:
+ * nothing here imports `audit-commands.ts`.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getErrorMessage } from '../cli-helpers.js';
+export const SUPPORTED_ARTIFACT_KINDS = [
+    'decision',
+    'prompt',
+    'machine-output',
+    'narrative'
+];
+export function isSupportedArtifactKind(value) {
+    return SUPPORTED_ARTIFACT_KINDS.includes(value);
+}
+/** Whitelist of supported `--llm-provider` values for `peaks audit goal`. */
+export const SUPPORTED_LLM_PROVIDERS = ['anthropic', 'stub'];
+/**
+ * The real provider is the default: `peaks audit goal` is the entry gate for
+ * every peaks-* workflow, so it must audit by default and only scaffold when
+ * a caller explicitly asks for `stub`.
+ */
+export const DEFAULT_LLM_PROVIDER = 'anthropic';
+export function isSupportedLlmProvider(value) {
+    return SUPPORTED_LLM_PROVIDERS.includes(value);
+}
+/** The one hint every `--project` refusal carries, verbatim. */
+export const PROJECT_PATH_HINT = 'Verify the project path exists and is a directory';
+/** The one hint every scanner-failure refusal carries, verbatim. */
+export const SCANNER_HINT = 'Inspect scanner logs and re-run with the same --project path';
+export function validateProjectRoot(projectArg) {
+    const projectRoot = resolve(projectArg);
+    if (!existsSync(projectRoot)) {
+        return {
+            ok: false,
+            code: 'PROJECT_NOT_FOUND',
+            message: `project path does not exist: ${projectArg}`
+        };
+    }
+    let stat;
+    try {
+        stat = statSync(projectRoot);
+    }
+    catch (error) {
+        return { ok: false, code: 'INVALID_PROJECT', message: getErrorMessage(error) };
+    }
+    if (!stat.isDirectory()) {
+        return {
+            ok: false,
+            code: 'INVALID_PROJECT',
+            message: `project path is not a directory: ${projectArg}`
+        };
+    }
+    return { ok: true, projectRoot };
+}

package/dist/cli/commands/audit-commands.d.ts

@@ -1,41 +1,17 @@
 /**
  * peaks audit * CLI surface — Slice L2.1 + L2.3 P2-a.
  *
- * Registers the new `peaks audit` top-level command with the
- * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
+ * Registers the `peaks audit` top-level command with the `red-lines` (L2.1),
+ * `static` (L2.3 P2-a), `prose-ratio`, `goal` and `artifact` subcommands.
  * Per `peaks-loop-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
  * we verified that no `peaks audit` top-level exists; this is the only
  * file that owns the registration.
+ *
+ * The action bodies live in `audit-<responsibility>-runners.ts` siblings; this
+ * file only wires the commands and delegates. Each delegate preserves the
+ * original callback's declared arity.
  */
 import type { Command } from 'commander';
-import { type AgentShieldState } from '../../services/audit/static-service.js';
 import { type ProgramIO } from '../cli-helpers.js';
-import type { AuditGoalOutput } from '../../services/audit/audit-goal-types.js';
-import type { RedLineAudit } from '../../services/audit/types.js';
-import { type AuditDecisionRecord } from '../../services/audit/decision-writer.js';
-/** `audit-failed` is a failure envelope's status — never a scaffold, never a success. */
-export type AuditGoalStatus = 'audit-complete' | 'scaffold-only' | 'audit-failed';
-export interface AuditGoalData {
-    readonly status: AuditGoalStatus;
-    /** Which LLM produced (or failed to produce) the audit. `unresolved` = rejected before binding. */
-    readonly providerBinding: 'anthropic-messages-api' | 'stub' | 'unresolved';
-    readonly need: string;
-    readonly projectRoot: string;
-    /** The validated 6-dimension audit. Present on success only. */
-    readonly result?: AuditGoalOutput;
-    /** The bound model. Present on a real run only. */
-    readonly model?: string;
-    /**
-     * Environment variables the binding needed and did not find. Present on a
-     * binding failure only, and verbatim: `fail()` redacts `message`, so this
-     * is the channel that reliably names what the operator must set.
-     */
-    readonly missingEnv?: readonly string[];
-}
-export interface StaticAuditData {
-    readonly audit: RedLineAudit;
-    readonly agentShield: AgentShieldState;
-    /** Populated only when `--record` is passed. Persisted decision record path. */
-    readonly decision?: AuditDecisionRecord;
-}
+export type { AuditGoalData, AuditGoalStatus, StaticAuditData } from './audit-command-shared.js';
 export declare function registerAuditCommands(program: Command, io: ProgramIO): void;