@latysh-development/monolith 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -160,7 +160,7 @@ listing — not an official partnership, endorsement or certification.
 
 ## Project Status
 
-**Alpha** (`0.1.0-alpha.1`). The API and CLI are experimental and may change
+**Alpha** (`0.1.0-alpha.2`). The API and CLI are experimental and may change
 without notice. Published to npm under the alpha dist-tag. Durable State and the Coordinatorium
 (`monolith durable`, `monolith mission`) are experimental and are not part of
 the Quick Start.

package/dist/cli/index.js

@@ -12,6 +12,7 @@
  *   monolith brief       — deterministic, bounded project context summary
  *   monolith durable     — inspect/verify/maintain Durable State task logs
  *   monolith idea        — capture and recall deferred ideas (add/list/show)
+ *   monolith finalize    — plan/apply a controlled story finalization (documentation sync)
  *   monolith update      — add missing Idea Capture infrastructure to an existing instance
  *   monolith ui          — launch Mission Control (read-only dashboard)
  */
@@ -42,6 +43,8 @@ Commands:
               list | show | assess | packet | verify | retention.
   idea        Capture a deferred thought without leaving the current task, and
               recall it later: add | list | show. Plain Markdown files, no LLM.
+  finalize    Close a story with checked preconditions and controlled documentation
+              updates: plan (read-only) | apply --approve <digest>.
   update      Bring an existing instance up to Idea Capture & Recall. Preview by
               default (changes nothing). --apply creates MONOLITH-managed files
               and may add or refresh managed sections inside your existing
@@ -74,6 +77,10 @@ Idea usage:
   monolith idea list
   monolith idea show <id>
 
+Finalize usage:
+  monolith finalize plan  --proposal <file|-> [--json]
+  monolith finalize apply --proposal <file|-> --approve <digest> [--json]
+
 Update usage:
   monolith update [--apply]
 
@@ -169,6 +176,11 @@ async function main() {
             await runIdeaCommand(args.slice(1));
             break;
         }
+        case 'finalize': {
+            const { runFinalizeCommand } = await import('../finalize/cli.js');
+            process.exitCode = await runFinalizeCommand(args.slice(1));
+            break;
+        }
         case 'update': {
             const { runUpdate } = await import('../update/cli.js');
             process.exitCode = await runUpdate(args.slice(1));

package/dist/finalize/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `monolith finalize plan|apply` (DOCSYNC-001, ADR-022).
+ *
+ * `plan` is read-only. `apply` writes only with `--approve <digest>` taken from
+ * a `plan` the owner reviewed. Exit codes: 0 ok / already finalized; 1 usage or
+ * unreadable proposal; 2 not ready / refused (nothing written); 3 incomplete
+ * (partially applied — see the output).
+ */
+export declare function runFinalizeCommand(args: string[], targetDir?: string): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/finalize/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/finalize/cli.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAuFH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBnG"}

package/dist/finalize/cli.js

@@ -0,0 +1,134 @@
+/* eslint-disable no-console */
+/**
+ * `monolith finalize plan|apply` (DOCSYNC-001, ADR-022).
+ *
+ * `plan` is read-only. `apply` writes only with `--approve <digest>` taken from
+ * a `plan` the owner reviewed. Exit codes: 0 ok / already finalized; 1 usage or
+ * unreadable proposal; 2 not ready / refused (nothing written); 3 incomplete
+ * (partially applied — see the output).
+ */
+import { lstatSync, readFileSync } from 'fs';
+import { applyFinalization, planFinalization } from './core.js';
+import { parseProposal } from './proposal.js';
+const USAGE = `Usage:
+  monolith finalize plan  --proposal <file|-> [--json]
+  monolith finalize apply --proposal <file|-> --approve <digest> [--json]`;
+const MAX_PROPOSAL_BYTES = 4 * 1024 * 1024;
+// eslint-disable-next-line no-control-regex
+const printable = (s) => s.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+function parseFlags(args, allowApprove) {
+    const f = { json: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json')
+            f.json = true;
+        else if (a === '--proposal' || (allowApprove && a === '--approve')) {
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('--'))
+                throw new Error(`${a} needs a value.\n${USAGE}`);
+            const key = a === '--proposal' ? 'proposal' : 'approve';
+            if (f[key] !== undefined)
+                throw new Error(`${a} was given more than once.\n${USAGE}`);
+            f[key] = v;
+            i++;
+        }
+        else
+            throw new Error(`Unexpected argument ${JSON.stringify(printable(a))}.\n${USAGE}`);
+    }
+    if (f.proposal === undefined)
+        throw new Error(`--proposal is required.\n${USAGE}`);
+    if (allowApprove && f.approve === undefined)
+        throw new Error(`--approve <digest> is required: run \`monolith finalize plan\`, review it, then pass its digest.\n${USAGE}`);
+    return f;
+}
+async function readProposal(src) {
+    let raw;
+    if (src === '-') {
+        const chunks = [];
+        let n = 0;
+        for await (const c of process.stdin) {
+            n += c.length;
+            if (n > MAX_PROPOSAL_BYTES)
+                throw new Error('proposal on stdin is too large.');
+            chunks.push(c);
+        }
+        raw = Buffer.concat(chunks).toString('utf8');
+    }
+    else {
+        const st = lstatSync(src);
+        if (!st.isFile())
+            throw new Error(`${src} is not a regular file.`);
+        if (st.size > MAX_PROPOSAL_BYTES)
+            throw new Error(`${src} is too large.`);
+        raw = readFileSync(src, 'utf8');
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`proposal is not valid JSON: ${err.message}`);
+    }
+    const parsed = parseProposal(json);
+    if (!parsed.ok)
+        throw new Error(`invalid proposal:\n${parsed.errors.map((e) => `  - ${e}`).join('\n')}`);
+    return parsed.proposal;
+}
+function printPlan(pl) {
+    console.log(`Finalization plan for ${printable(pl.storyId)}: ${pl.status}${pl.partial ? ' (PARTIAL: an earlier run was interrupted; apply rolls it forward)' : ''}`);
+    console.log('\nPreconditions:');
+    for (const c of pl.checks)
+        console.log(`  [${c.status}] ${c.id}: ${printable(c.detail)}\n         source: ${printable(c.source)}`);
+    console.log('\nTargets (in write order, active.md last):');
+    for (const t of pl.targets)
+        console.log(`  [${t.state}] ${t.id} → ${printable(t.path)}${t.state === 'done' ? '' : ` — ${printable(t.reason)}`}`);
+    for (const d of pl.diagnostics)
+        console.log(`\nNote: ${printable(d)}`);
+    if (pl.status === 'READY')
+        console.log(`\nDigest: ${pl.digest}\nOwner approval: monolith finalize apply --proposal <same file> --approve ${pl.digest}\nThe digest shows this plan is unchanged; it does not prove who approves it. Do not run apply unless the owner approved this exact plan.`);
+}
+function printApply(r) {
+    console.log(`Finalization of ${printable(r.storyId)}: ${r.status}`);
+    if (r.applied.length > 0)
+        console.log(`  written: ${r.applied.join(', ')}`);
+    if (r.status !== 'FINALIZED' && r.pending.length > 0)
+        console.log(`  not written: ${r.pending.join(', ')}`);
+    if (r.failed)
+        console.log(`  failed: ${r.failed.target}${r.failed.publication ? ` [${r.failed.publication}]` : ''}: ${printable(r.failed.message)}`);
+    for (const d of r.diagnostics)
+        console.log(`  ${printable(d)}`);
+    if (r.status === 'REFUSED')
+        for (const c of r.plan.checks.filter((x) => x.status !== 'PASS'))
+            console.log(`  [${c.status}] ${c.id}: ${printable(c.detail)}`);
+}
+export async function runFinalizeCommand(args, targetDir = process.cwd()) {
+    const sub = args[0];
+    try {
+        if (sub === 'plan') {
+            const f = parseFlags(args.slice(1), false);
+            const pl = planFinalization(targetDir, await readProposal(f.proposal));
+            if (f.json)
+                console.log(JSON.stringify(pl, null, 2));
+            else
+                printPlan(pl);
+            return pl.status === 'NOT_READY' ? 2 : 0;
+        }
+        if (sub === 'apply') {
+            const f = parseFlags(args.slice(1), true);
+            const r = await applyFinalization(targetDir, await readProposal(f.proposal), f.approve, {
+                onWarning: (w) => console.error(`warning: ${printable(w.message)}`),
+            });
+            if (f.json)
+                console.log(JSON.stringify(r, null, 2));
+            else
+                printApply(r);
+            return r.status === 'FINALIZED' || r.status === 'ALREADY_FINALIZED' ? 0 : r.status === 'REFUSED' ? 2 : 3;
+        }
+        console.error(`Unknown finalize subcommand: ${sub === undefined ? '(none)' : printable(sub)}\n${USAGE}`);
+        return 1;
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}

package/dist/finalize/core.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Deterministic story finalization (DOCSYNC-001, ADR-022).
+ *
+ * `planFinalization` is read-only: it validates a proposal against the
+ * instance, evaluates explicit preconditions (PASS / FAIL / NOT_VERIFIED),
+ * classifies every write target and returns a digest that binds an owner's
+ * approval to exactly what was inspected. `applyFinalization` re-plans under a
+ * cross-process lock and writes only if the digest still matches.
+ *
+ * Consistency model (narrower than a transaction, deliberately): there is no
+ * rollback. Targets are written one at a time in a fixed order with `active.md`
+ * LAST, every write is an atomic single-file publish (src/root safe-write), and
+ * each target has a deterministic "already done" predicate. An interruption
+ * leaves a state that `planFinalization` reports as partial and that re-running
+ * plan + apply rolls forward; success is only reported after a post-write
+ * re-read of every target. See ADR-022.
+ *
+ * Reused, not reimplemented: safe reads/writes and containment (src/root),
+ * the cross-process lock (src/coordinatorium/lock), the Current Story section
+ * extractor of `monolith brief` (src/brief/story).
+ */
+import { type ConfigRead, type FsOps, type WriteWarning } from '../root/index.js';
+import { type LockOptions } from '../coordinatorium/lock.js';
+import { type FinalizationProposal } from './proposal.js';
+export type CheckStatus = 'PASS' | 'FAIL' | 'NOT_VERIFIED';
+export type TargetKind = 'capsule' | 'execution-history' | 'story-index' | 'doc' | 'handoff' | 'active';
+export type TargetState = 'pending' | 'done' | 'conflict' | 'missing' | 'unreadable';
+export type PlanStatus = 'READY' | 'NOT_READY' | 'ALREADY_FINALIZED';
+export type ApplyStatus = 'FINALIZED' | 'ALREADY_FINALIZED' | 'REFUSED' | 'INCOMPLETE';
+export interface Check {
+    id: string;
+    status: CheckStatus;
+    detail: string;
+    /** Where the verdict comes from (a MONOLITH computation vs. attested evidence). */
+    source: string;
+}
+export interface PlannedTarget {
+    id: string;
+    kind: TargetKind;
+    /** Project-relative, `/`-separated. */
+    path: string;
+    state: TargetState;
+    reason: string;
+    /** sha256 of the file as inspected, `ABSENT`, or `DONE`. Part of the digest. */
+    base: string;
+    /** What will be written/appended; omitted for done/blocked targets and for opaque documents. */
+    preview?: string;
+}
+export interface FinalizationPlan {
+    status: PlanStatus;
+    storyId: string;
+    /** Approval token: sha256 over the proposal, every target's state/base and the evidence inspected. */
+    digest: string;
+    /** True when some, but not all, targets are already in their final state (an earlier run was interrupted). */
+    partial: boolean;
+    checks: Check[];
+    targets: PlannedTarget[];
+    diagnostics: string[];
+}
+export interface ApplyResult {
+    status: ApplyStatus;
+    storyId: string;
+    plan: FinalizationPlan;
+    applied: string[];
+    pending: string[];
+    failed?: {
+        target: string;
+        message: string;
+        publication?: string;
+    };
+    diagnostics: string[];
+}
+export interface FinalizeOptions {
+    /** Test-only fault injection for the safe-write primitives. */
+    ops?: Partial<FsOps>;
+    lock?: LockOptions;
+    onWarning?: (w: WriteWarning) => void;
+}
+export interface FinalizeConfig {
+    requiredDocs: Array<{
+        path: string;
+        label: string;
+    }>;
+    allowedDocs: string[];
+    errors: string[];
+}
+export declare function readFinalizeConfig(config: ConfigRead): FinalizeConfig;
+export declare function renderCapsule(p: FinalizationProposal): string;
+/** Evidence older than this many days before the finalization date is not accepted. */
+export declare const EVIDENCE_MAX_AGE_DAYS = 7;
+export type ActiveIdentity = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Structural identity of the active story (DOCSYNC-007). The ONLY source is the
+ * `**Story:** <id> …` field line inside `## Current Story` (same grammar as the
+ * evidence files and `## Last Finalization`); its FIRST token is the id. Ids
+ * mentioned in titles, descriptions, comments, code fences or other fields carry
+ * no authority. Zero, several, or malformed field lines → no identity (fail closed).
+ */
+export declare function activeStoryIdentity(currentStoryBody: string): ActiveIdentity;
+export declare function planFinalization(targetDir: string, proposal: FinalizationProposal): FinalizationPlan;
+export declare function applyFinalization(targetDir: string, proposal: FinalizationProposal, approvedDigest: string, opts?: FinalizeOptions): Promise<ApplyResult>;
+//# sourceMappingURL=core.d.ts.map

package/dist/finalize/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/finalize/core.ts"],"names":[],"mappings":"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"}