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

package/dist/init/scaffold.js

@@ -2,6 +2,7 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, dirname, resolve, relative, basename } from 'path';
 import { fileURLToPath } from 'url';
+import { BLOCK_IDS, blockBody, placeholderFor, renderBlock } from '../managed/index.js';
 import { SafeWriteError, createFile, openParent, probeTarget, projectBoundary, resolveMonolithRootValue, } from '../root/index.js';
 const INSTRUCTION_FILE_MAP = {
     claude: 'CLAUDE.md',
@@ -11,8 +12,8 @@ const INSTRUCTION_FILE_MAP = {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Works both from dist/init/ (compiled) and src/init/ (tsx)
-const TEMPLATES_ROOT = resolve(__dirname, '..', '..', 'templates', 'default-instance');
-function substitute(content, vars) {
+export const TEMPLATES_ROOT = resolve(__dirname, '..', '..', 'templates', 'default-instance');
+export function substitute(content, vars) {
     return content.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
 function stripTemplateSuffix(p) {
@@ -63,6 +64,8 @@ function buildVars(config) {
             .split('\n')
             .join('\n  '),
         DRIFT_LOG_PATH: `${r}/enforcement/drift-log.json`,
+        // Same managed blocks `monolith update` writes into existing instances.
+        ...Object.fromEntries(BLOCK_IDS.map((id) => [placeholderFor(id), renderBlock(id, blockBody(id, r)).replace(/\n$/, '')])),
     };
 }
 // Relative to config.monolithRoot (`r`). Shared between createEmptyDirs
@@ -71,6 +74,7 @@ function buildVars(config) {
 const GITKEEP_DIRS = [
     'memory/working/phases',
     'memory/execution/traces',
+    'memory/long-term/ideas',
     'protocols/engineering',
     'learning/mistakes/architecture',
     'learning/mistakes/dependencies',

package/dist/managed/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Managed blocks (DX-UPDATE-003): the one mechanism by which `monolith init`
+ * and `monolith update` put MONOLITH-owned text into a file the user also owns
+ * (CLAUDE.md, AGENTS.md, routing-map, skills index) or into a MONOLITH-owned
+ * file the user may extend (`AGENT.md`).
+ *
+ *   <!-- monolith:begin <id> sha256=<16 hex of the body> -->
+ *   ...body...
+ *   <!-- monolith:end <id> -->
+ *
+ * The checksum is what makes a refresh safe without a stored template version:
+ * a block whose body still matches its own checksum was never edited, so it is
+ * ours to refresh; a block that does not match carries a user edit and is left
+ * alone (CONFLICT). Everything outside the markers is never read for meaning
+ * and never changed. Markers inside fenced code blocks are examples, not blocks.
+ * This is not a Markdown parser: it knows lines, fences and these markers.
+ */
+export declare const BLOCK_IDS: readonly ["bootstrap", "agent", "routing-idea", "index-idea"];
+export type BlockId = (typeof BLOCK_IDS)[number];
+/** `{{MANAGED_<ID>}}` placeholder name used by the init templates. */
+export declare function placeholderFor(id: BlockId): string;
+export declare function bodyHash(body: string): string;
+/** The body of a block for a given instance root. */
+export declare function blockBody(id: BlockId, monolithRoot: string): string;
+/** The block as it is written to a file (markers + body), ending in a newline. */
+export declare function renderBlock(id: BlockId, body: string, eol?: string): string;
+export type BlockState = {
+    state: 'absent';
+}
+/** Exactly one well-formed block whose body matches its checksum. `current`: also equals the template. */
+ | {
+    state: 'pristine';
+    current: boolean;
+    from: number;
+    to: number;
+    lines: string[];
+} | {
+    state: 'edited';
+    detail: string;
+} | {
+    state: 'malformed';
+    detail: string;
+};
+/** Classify `id` in `text` against the template body `desired`. */
+export declare function inspectBlock(text: string, id: BlockId, desired: string): BlockState;
+/** `text` plus the block, appended; every existing byte stays in place. */
+export declare function appendBlock(text: string, id: BlockId, body: string): string;
+/** `text` with only the lines of the block replaced. */
+export declare function refreshBlock(text: string, state: Extract<BlockState, {
+    state: 'pristine';
+}>, id: BlockId, body: string): string;
+export type Planned = {
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    detail: string;
+};
+/**
+ * `text` with the block appended, or the reason that is not safe. Safe means the
+ * result, read back by `inspectBlock`, shows exactly one well-formed, unedited
+ * block that equals the template, and every original byte is still in place.
+ * An unclosed code fence or HTML comment in `text` swallows the new markers (the next run would
+ * not see the block and append another), so it is refused up front.
+ */
+export declare function planAppend(text: string, id: BlockId, body: string): Planned;
+/** `text` with the block refreshed in place, or the reason that is not safe (see `planAppend`). */
+export declare function planRefresh(text: string, state: Extract<BlockState, {
+    state: 'pristine';
+}>, id: BlockId, body: string): Planned;
+/** Text with fenced code blocks and HTML comments removed: what an assistant reads as instructions. */
+export declare function prose(text: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/managed/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/managed/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,eAAO,MAAM,SAAS,+DAAgE,CAAC;AACvF,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAElD;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAMD,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAGzE;AA8FD,MAAM,MAAM,UAAU,GAClB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE;AACrB,0GAA0G;GACxG;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAClF;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAyBnF;AAMD,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAO/H;AAED,MAAM,MAAM,OAAO,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAW3E;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM/H;AAQD,uGAAuG;AACvG,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1C"}

package/dist/managed/index.js

@@ -0,0 +1,222 @@
+/**
+ * Managed blocks (DX-UPDATE-003): the one mechanism by which `monolith init`
+ * and `monolith update` put MONOLITH-owned text into a file the user also owns
+ * (CLAUDE.md, AGENTS.md, routing-map, skills index) or into a MONOLITH-owned
+ * file the user may extend (`AGENT.md`).
+ *
+ *   <!-- monolith:begin <id> sha256=<16 hex of the body> -->
+ *   ...body...
+ *   <!-- monolith:end <id> -->
+ *
+ * The checksum is what makes a refresh safe without a stored template version:
+ * a block whose body still matches its own checksum was never edited, so it is
+ * ours to refresh; a block that does not match carries a user edit and is left
+ * alone (CONFLICT). Everything outside the markers is never read for meaning
+ * and never changed. Markers inside fenced code blocks are examples, not blocks.
+ * This is not a Markdown parser: it knows lines, fences and these markers.
+ */
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Works from src/managed/ and dist/managed/ alike.
+const MANAGED_TEMPLATES = resolve(__dirname, '..', '..', 'templates', 'default-instance', 'managed');
+export const BLOCK_IDS = ['bootstrap', 'agent', 'routing-idea', 'index-idea'];
+/** `{{MANAGED_<ID>}}` placeholder name used by the init templates. */
+export function placeholderFor(id) {
+    return `MANAGED_${id.toUpperCase().replace(/-/g, '_')}`;
+}
+export function bodyHash(body) {
+    return createHash('sha256').update(normalize(body)).digest('hex').slice(0, 16);
+}
+function normalize(s) {
+    return s.replace(/\r\n/g, '\n').replace(/\s+$/, '');
+}
+/** The body of a block for a given instance root. */
+export function blockBody(id, monolithRoot) {
+    const raw = readFileSync(join(MANAGED_TEMPLATES, `${id}.md`), 'utf8');
+    return normalize(raw.replace(/\{\{MONOLITH_ROOT\}\}/g, monolithRoot));
+}
+/** The block as it is written to a file (markers + body), ending in a newline. */
+export function renderBlock(id, body, eol = '\n') {
+    const lines = [`<!-- monolith:begin ${id} sha256=${bodyHash(body)} -->`, ...normalize(body).split('\n'), `<!-- monolith:end ${id} -->`];
+    return lines.join(eol) + eol;
+}
+const MARKER = /^<!-- monolith:(begin|end) ([a-z-]+)(?: sha256=([0-9a-f]{16}))? -->$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+function splitLines(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+/** A leading UTF-8 BOM is not part of the first line's Markdown. */
+const stripBom = (l, i) => (i === 0 ? l.replace(/^\uFEFF/, '') : l);
+/**
+ * Per line: is it a fence line or inside a fenced code block? Same rules as
+ * CommonMark for the cases that matter here: a fence is 3+ backticks or tildes
+ * (at most 3 spaces of indent), it closes on the same character with at least
+ * the same length and nothing after it, and a block left open runs to the end
+ * of the file. `open` tells whether the text ends inside such a block.
+ */
+function scanFences(lines) {
+    const hidden = [];
+    let fence = null;
+    for (const [i, l] of lines.entries()) {
+        const t = stripBom(l, i).replace(/\r?\n$/, '');
+        if (fence === null) {
+            const o = FENCE_OPEN.exec(t);
+            if (o && !(o[1][0] === '`' && o[2].includes('`'))) {
+                fence = { ch: o[1][0], len: o[1].length };
+                hidden.push(true);
+            }
+            else
+                hidden.push(false);
+        }
+        else {
+            const c = FENCE_CLOSE.exec(t);
+            if (c && c[1][0] === fence.ch && c[1].length >= fence.len)
+                fence = null;
+            hidden.push(true);
+        }
+    }
+    return { hidden, open: fence !== null };
+}
+/**
+ * Per line (outside fences): does it start inside an HTML comment? `open` tells
+ * whether the text ends inside one. A line that is exactly a marker opens and
+ * closes its own comment and does not change the state. Deliberately naive: a
+ * `<!--` in inline code counts as a comment, which can only make us refuse.
+ */
+function scanComments(lines, hidden) {
+    const inside = [];
+    let open = false;
+    lines.forEach((l, i) => {
+        inside.push(open);
+        if (hidden[i])
+            return;
+        const t = stripBom(l, i).replace(/\r?\n$/, '');
+        if (!open && MARKER.test(t.trim()))
+            return;
+        let at = 0;
+        for (;;) {
+            if (open) {
+                const end = t.indexOf('-->', at);
+                if (end < 0)
+                    break;
+                open = false;
+                at = end + 3;
+            }
+            else {
+                const start = t.indexOf('<!--', at);
+                if (start < 0)
+                    break;
+                open = true;
+                at = start + 4;
+            }
+        }
+    });
+    return { inside, open };
+}
+function markers(lines) {
+    const out = [];
+    const { hidden } = scanFences(lines);
+    const { inside } = scanComments(lines, hidden);
+    lines.forEach((l, i) => {
+        if (hidden[i])
+            return;
+        const t = l.replace(/\r?\n$/, '');
+        const m = MARKER.exec(t.trim());
+        if (m)
+            out.push({ kind: m[1], id: m[2], hash: m[3], line: i, commented: inside[i] });
+    });
+    return out;
+}
+/** Classify `id` in `text` against the template body `desired`. */
+export function inspectBlock(text, id, desired) {
+    const lines = splitLines(text);
+    const all = markers(lines);
+    const mine = all.filter((m) => m.id === id);
+    if (mine.length === 0)
+        return { state: 'absent' };
+    if (mine.some((m) => m.commented)) {
+        return { state: 'malformed', detail: `a "${id}" marker sits inside an HTML comment, so the block is not active` };
+    }
+    const begins = mine.filter((m) => m.kind === 'begin');
+    const ends = mine.filter((m) => m.kind === 'end');
+    if (begins.length !== 1 || ends.length !== 1) {
+        return { state: 'malformed', detail: `${begins.length} begin and ${ends.length} end marker(s) for "${id}"; exactly one of each is required` };
+    }
+    const [b] = begins;
+    const [e] = ends;
+    if (e.line < b.line)
+        return { state: 'malformed', detail: `the "${id}" end marker precedes its begin marker` };
+    if (all.some((m) => m !== b && m !== e && m.line > b.line && m.line < e.line)) {
+        return { state: 'malformed', detail: `another managed marker sits inside the "${id}" block` };
+    }
+    if (b.hash === undefined)
+        return { state: 'malformed', detail: `the "${id}" begin marker has no checksum` };
+    const body = lines.slice(b.line + 1, e.line).join('');
+    if (bodyHash(body) !== b.hash) {
+        return { state: 'edited', detail: `the text inside the "${id}" block was edited after MONOLITH wrote it` };
+    }
+    return { state: 'pristine', current: normalize(body) === normalize(desired), from: b.line, to: e.line, lines };
+}
+function eolOf(text) {
+    return text.includes('\r\n') ? '\r\n' : '\n';
+}
+/** `text` plus the block, appended; every existing byte stays in place. */
+export function appendBlock(text, id, body) {
+    const eol = eolOf(text);
+    const sep = text.length === 0 ? '' : text.endsWith('\n') ? eol : eol + eol;
+    return text + sep + renderBlock(id, body, eol);
+}
+/** `text` with only the lines of the block replaced. */
+export function refreshBlock(text, state, id, body) {
+    const eol = eolOf(text);
+    const rendered = renderBlock(id, body, eol);
+    // The end-marker line may be the unterminated last line of the file: keep it that way.
+    const unterminated = !/\n$/.test(state.lines[state.to]);
+    const block = unterminated ? rendered.slice(0, -eol.length) : rendered;
+    return state.lines.slice(0, state.from).join('') + block + state.lines.slice(state.to + 1).join('');
+}
+/**
+ * `text` with the block appended, or the reason that is not safe. Safe means the
+ * result, read back by `inspectBlock`, shows exactly one well-formed, unedited
+ * block that equals the template, and every original byte is still in place.
+ * An unclosed code fence or HTML comment in `text` swallows the new markers (the next run would
+ * not see the block and append another), so it is refused up front.
+ */
+export function planAppend(text, id, body) {
+    if (scanFences(splitLines(text)).open) {
+        return { ok: false, detail: 'the file ends inside an unclosed fenced code block (``` or ~~~), which would hide the new block' };
+    }
+    const lines = splitLines(text);
+    if (scanComments(lines, scanFences(lines).hidden).open) {
+        return { ok: false, detail: 'the file ends inside an unclosed HTML comment (<!--), which would hide the new block' };
+    }
+    const content = appendBlock(text, id, body);
+    if (!content.startsWith(text))
+        return { ok: false, detail: 'the append would not keep the existing bytes in place' };
+    return verified(content, id, body);
+}
+/** `text` with the block refreshed in place, or the reason that is not safe (see `planAppend`). */
+export function planRefresh(text, state, id, body) {
+    const content = refreshBlock(text, state, id, body);
+    const head = state.lines.slice(0, state.from).join('');
+    const tail = state.lines.slice(state.to + 1).join('');
+    if (!content.startsWith(head) || !content.endsWith(tail))
+        return { ok: false, detail: 'the refresh would change text outside the block' };
+    return verified(content, id, body);
+}
+function verified(content, id, body) {
+    const st = inspectBlock(content, id, body);
+    if (st.state === 'pristine' && st.current)
+        return { ok: true, content };
+    return { ok: false, detail: `the written block would not be recognised as current (${st.state === 'pristine' ? 'stale' : st.state})` };
+}
+/** Text with fenced code blocks and HTML comments removed: what an assistant reads as instructions. */
+export function prose(text) {
+    const lines = splitLines(text);
+    const { hidden } = scanFences(lines);
+    return lines.filter((_, i) => !hidden[i]).join('').replace(/<!--[\s\S]*?-->/g, '');
+}

package/dist/root/index.d.ts

@@ -91,6 +91,13 @@ export interface ProjectFileOptions {
     maxBytes?: number;
     /** Accept a zero-byte file. Defaults to false. */
     allowEmpty?: boolean;
+    /**
+     * Refuse (FILE_UNREADABLE) content that is not strictly valid UTF-8 or that
+     * contains a NUL byte (UTF-16 without BOM), instead of replacing bad bytes
+     * with U+FFFD. For callers that write the text back: a lossy read would
+     * corrupt the file. A UTF-8 BOM is kept in the string. Defaults to false.
+     */
+    strictUtf8?: boolean;
 }
 /**
  * Options of the unified reader. `boundary` is mandatory and explicit: an

package/dist/root/index.d.ts.map

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

package/dist/root/index.js

@@ -348,7 +348,19 @@ export function readBoundedFile(abs, label, opts, wantContent) {
                 return fail('FILE_TOO_LARGE', `${label} grew beyond the limit of ${maxBytes} bytes while being read.`);
             chunks.push(buf.subarray(0, n));
         }
-        return { ok: true, path: abs, size: total, content: Buffer.concat(chunks).toString('utf8') };
+        const bytes = Buffer.concat(chunks);
+        if (opts.strictUtf8) {
+            try {
+                if (bytes.includes(0))
+                    throw new Error('NUL byte');
+                const content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+                return { ok: true, path: abs, size: total, content };
+            }
+            catch {
+                return fail('FILE_UNREADABLE', `${label} is not valid UTF-8 text (another encoding, UTF-16 or binary); MONOLITH does not convert encodings.`);
+            }
+        }
+        return { ok: true, path: abs, size: total, content: bytes.toString('utf8') };
     }
     catch (err) {
         return fail('FILE_UNREADABLE', `${label} cannot be read: ${errMsg(err)}`);

package/dist/update/cli.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `monolith update [--apply]` handler (DX-UPDATE-001). Preview is read-only.
+ * Exit codes: 0 ok (preview, or apply with integration complete), 1 error,
+ * 2 apply finished but manual actions remain (integration incomplete).
+ */
+export declare const UPDATE_USAGE = "Usage: monolith update [--apply]\n\nBrings an existing MONOLITH instance up to the current agent integration: a\nstable entry point (<root>/AGENT.md), the idea-capture skill, its routing and the\npointer in your AI instruction files.\n  (no flag)  Preview: shows the plan, writes nothing.\n  --apply    Performs the plan: ADD creates a missing MONOLITH file, UPDATE adds\n             or refreshes a managed block inside a file of yours.\n\nWhat is written, and what is not:\n  - MONOLITH text goes only into checksummed managed blocks\n    (<!-- monolith:begin ... -->). Appending leaves every existing byte in place;\n    refreshing replaces only an unedited block.\n  - A block you edited, a malformed block, a clashing section of yours, an\n    unclosed code fence (backticks or tildes) or HTML comment that would hide the block, a file that is not\n    valid UTF-8 (no encoding is converted) or an unreadable file is CONFLICT: nothing is written there and the plan says how\n    to resolve it. SKIP means left alone on purpose (e.g. your own skill).\n  - Your existing skills, memory, state.json, ideas and text are never overwritten.\n    Nothing is executed.\nInstances carry no template version, so state is read from the files. Safe to\nre-run. Not transactional and not coordinated between simultaneous runs: apply\nre-checks each file just before writing and skips one that changed. Exit code 2\nafter --apply means the integration is not complete (conflicts or skipped\nchanges remain).";
+export declare function runUpdate(args: string[], targetDir?: string): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/update/cli.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAKH,eAAO,MAAM,YAAY,+9CAuBR,CAAC;AA6ClB,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoC1F"}

package/dist/update/cli.js

@@ -0,0 +1,115 @@
+/* eslint-disable no-console */
+/**
+ * `monolith update [--apply]` handler (DX-UPDATE-001). Preview is read-only.
+ * Exit codes: 0 ok (preview, or apply with integration complete), 1 error,
+ * 2 apply finished but manual actions remain (integration incomplete).
+ */
+import { reportWriteWarning } from '../root/index.js';
+import { applyPlan, integrationComplete, planUpdate } from './index.js';
+export const UPDATE_USAGE = `Usage: monolith update [--apply]
+
+Brings an existing MONOLITH instance up to the current agent integration: a
+stable entry point (<root>/AGENT.md), the idea-capture skill, its routing and the
+pointer in your AI instruction files.
+  (no flag)  Preview: shows the plan, writes nothing.
+  --apply    Performs the plan: ADD creates a missing MONOLITH file, UPDATE adds
+             or refreshes a managed block inside a file of yours.
+
+What is written, and what is not:
+  - MONOLITH text goes only into checksummed managed blocks
+    (<!-- monolith:begin ... -->). Appending leaves every existing byte in place;
+    refreshing replaces only an unedited block.
+  - A block you edited, a malformed block, a clashing section of yours, an
+    unclosed code fence (backticks or tildes) or HTML comment that would hide the block, a file that is not
+    valid UTF-8 (no encoding is converted) or an unreadable file is CONFLICT: nothing is written there and the plan says how
+    to resolve it. SKIP means left alone on purpose (e.g. your own skill).
+  - Your existing skills, memory, state.json, ideas and text are never overwritten.
+    Nothing is executed.
+Instances carry no template version, so state is read from the files. Safe to
+re-run. Not transactional and not coordinated between simultaneous runs: apply
+re-checks each file just before writing and skips one that changed. Exit code 2
+after --apply means the integration is not complete (conflicts or skipped
+changes remain).`;
+function printable(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+function printPlan(plan) {
+    const width = Math.max(...plan.items.map((i) => i.action.length));
+    for (const i of plan.items)
+        console.log(`  ${i.action.padEnd(width)}  ${printable(i.path)}\n  ${' '.repeat(width)}  ${i.reason}`);
+}
+function printEffects(items) {
+    const todo = items.filter((i) => i.action === 'ADD' || i.action === 'UPDATE');
+    if (todo.length === 0)
+        return;
+    console.log('\nWhy this is safe: ADD only creates files that do not exist; UPDATE only adds or refreshes a');
+    console.log('managed block and is checked to leave all other text unchanged. Nothing else is written.');
+    console.log('After --apply:');
+    for (const i of todo)
+        console.log(`  - ${printable(i.path)}: ${i.effect ?? ''}`);
+}
+function printProposals(items) {
+    for (const i of items.filter((x) => x.action === 'CONFLICT' && x.proposal)) {
+        console.log(`\n--- Manual fallback for ${printable(i.path)}: add this block yourself ---\n${i.proposal}--- end ---`);
+    }
+}
+function printChain(plan) {
+    console.log('\nConsistency (instructions → routing → skill → CLI → storage):');
+    for (const c of plan.chain)
+        console.log(`  ${c.ok ? 'ok  ' : 'FAIL'}  ${c.link}: ${printable(c.detail)}`);
+}
+function verdict(plan, stale = []) {
+    const pending = plan.items.filter((i) => i.action === 'ADD' || i.action === 'UPDATE').length;
+    const manual = plan.items.filter((i) => i.action === 'CONFLICT').length;
+    const broken = plan.chain.filter((c) => !c.ok).length;
+    if (pending === 0 && manual === 0 && broken === 0 && stale.length === 0)
+        return 'Idea Capture integration: COMPLETE (the managed components are installed and pass the structural check; how an AI assistant behaves is not verified).';
+    const parts = [];
+    if (pending > 0)
+        parts.push(`${pending} change(s) to apply`);
+    if (manual > 0)
+        parts.push(`${manual} manual action(s)`);
+    if (stale.length > 0)
+        parts.push(`${stale.length} change(s) skipped because the file changed meanwhile`);
+    if (broken > 0 && parts.length === 0)
+        parts.push(`${broken} consistency check(s) failing`);
+    return `Idea Capture integration: INCOMPLETE (${parts.join(', ')}). A partly installed integration is not active.`;
+}
+export async function runUpdate(args, targetDir = process.cwd()) {
+    let apply = false;
+    for (const a of args) {
+        if (a === '--apply')
+            apply = true;
+        else {
+            console.error(`Unexpected argument ${JSON.stringify(printable(a))}.\n${UPDATE_USAGE}`);
+            return 1;
+        }
+    }
+    const plan = planUpdate(targetDir);
+    console.log(`monolith update — ${apply ? 'apply' : 'preview (nothing is written)'}`);
+    console.log(`Instance root: ${plan.monolithRoot}/\n`);
+    printPlan(plan);
+    if (!apply) {
+        printEffects(plan.items);
+        printProposals(plan.items);
+        printChain(plan);
+        console.log(`\n${verdict(plan)}`);
+        if (plan.items.some((i) => i.action === 'ADD' || i.action === 'UPDATE'))
+            console.log('Run `monolith update --apply` to perform the ADD / UPDATE items.');
+        return 0;
+    }
+    const result = applyPlan(targetDir, plan);
+    for (const w of result.warnings)
+        reportWriteWarning(w);
+    const list = (xs) => (xs.length ? ': ' + xs.map(printable).join(', ') : '');
+    console.log(`\nCreated ${result.created.length} file(s)${list(result.created)}.`);
+    console.log(`Updated ${result.updated.length} file(s)${list(result.updated)}.`);
+    if (result.stale.length > 0)
+        console.log(`Skipped (changed since planning)${list(result.stale)}. Re-run to plan again.`);
+    const after = planUpdate(targetDir);
+    printProposals(after.items);
+    printChain(after);
+    console.log(`\n${verdict(after, result.stale)}`);
+    return integrationComplete(after) && result.stale.length === 0 ? 0 : 2;
+}

package/dist/update/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `monolith update` (DX-UPDATE-001/003): bring an existing instance up to the
+ * current agent integration (stable `AGENT.md` entry point, Idea Capture)
+ * without touching project memory.
+ *
+ * Ownership model (no template version is stored in an instance, so state is
+ * read from the files themselves):
+ *  - MONOLITH-owned, created when absent: `<root>/AGENT.md`, the `idea-capture`
+ *    skill. An existing skill is never overwritten, whatever it contains.
+ *  - Mixed (user-owned file + MONOLITH text): CLAUDE.md / AGENTS.md /
+ *    .cursorrules / .windsurfrules, routing-map, skills index. MONOLITH text
+ *    lives only in checksummed managed blocks (src/managed). A missing block is
+ *    appended; an unedited block is refreshed in place; an edited, malformed or
+ *    competing one is a CONFLICT and nothing is written. Bytes outside a block
+ *    are never changed (asserted before every write).
+ *  - User memory (state.json, memory/, ideas): never touched.
+ *
+ * Reads use the bounded safe read; writes use the safe-write primitives
+ * (project boundary, no symlinks, exclusive create / atomic replace). Update is
+ * not transactional and not coordinated between processes (SEC-001B.3): apply
+ * re-plans just before writing and refuses a change whose preconditions moved;
+ * a re-run is the recovery. Nothing is executed and no user text is interpreted
+ * as code.
+ */
+import { RootContainmentError, type WriteWarning } from '../root/index.js';
+export type UpdateAction = 'ADD' | 'UPDATE' | 'UNCHANGED' | 'CONFLICT' | 'SKIP';
+export interface UpdateItem {
+    /** Path relative to the project root, `/`-separated. */
+    path: string;
+    action: UpdateAction;
+    /** Why, in one line. */
+    reason: string;
+    /** For CONFLICT: how to resolve it by hand. */
+    proposal?: string;
+    /** For ADD / UPDATE: the complete file content to write. */
+    content?: string;
+    /** For UPDATE: sha256 of the file as planned against; apply refuses if it moved. */
+    before?: string;
+    /** For ADD / UPDATE: what it makes available. */
+    effect?: string;
+}
+/** One link of Agent Instructions → Routing → Skill → CLI → Storage. */
+export interface ChainCheck {
+    link: string;
+    ok: boolean;
+    detail: string;
+}
+export interface UpdatePlan {
+    monolithRoot: string;
+    items: UpdateItem[];
+    chain: ChainCheck[];
+}
+/**
+ * Read-only. Throws RootContainmentError when the root/config is unusable and
+ * `Error` when the directory is not a MONOLITH instance.
+ */
+export declare function planUpdate(target: string): UpdatePlan;
+/**
+ * "Complete" is a structural statement: every managed component is installed,
+ * unedited-or-current, and the static chain checks out. It says nothing about
+ * what an AI model will do with the text. Integration is complete only when nothing is left to add, change or resolve AND every link of the chain checks out. */
+export declare function integrationComplete(plan: UpdatePlan): boolean;
+export interface ApplyResult {
+    created: string[];
+    updated: string[];
+    /** Planned changes not applied because the file changed since planning (or could not be written). */
+    stale: string[];
+    warnings: WriteWarning[];
+}
+/**
+ * Write every ADD and UPDATE of `plan`. The tree is re-planned first and an
+ * item is applied only if the file is exactly as planned: an `ADD` target that
+ * appeared is skipped, an `UPDATE` whose file changed is reported as stale and
+ * left alone. Stops at the first write failure (earlier files stay; re-run).
+ */
+export declare function applyPlan(target: string, plan: UpdatePlan): ApplyResult;
+export { RootContainmentError };
+//# sourceMappingURL=index.d.ts.map

package/dist/update/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/update/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAEL,oBAAoB,EAQpB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhF,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AA+ED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAgGrD;AAiCD;;;iKAGiK;AACjK,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAE7D;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qGAAqG;IACrG,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAUD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAsCvE;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}