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

package/dist/finalize/index.d.ts

@@ -0,0 +1,5 @@
+export { parseProposal, validateRelPath, PROPOSAL_SCHEMA_VERSION } from './proposal.js';
+export type { FinalizationProposal, ProposalParse, ExpectedCurrentStory } from './proposal.js';
+export { planFinalization, applyFinalization, readFinalizeConfig, renderCapsule } from './core.js';
+export type { ApplyResult, ApplyStatus, Check, CheckStatus, FinalizationPlan, FinalizeConfig, FinalizeOptions, PlanStatus, PlannedTarget, TargetKind, TargetState, } from './core.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/finalize/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxF,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACnG,YAAY,EACV,WAAW,EACX,WAAW,EACX,KAAK,EACL,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAC"}

package/dist/finalize/index.js

@@ -0,0 +1,2 @@
+export { parseProposal, validateRelPath, PROPOSAL_SCHEMA_VERSION } from './proposal.js';
+export { planFinalization, applyFinalization, readFinalizeConfig, renderCapsule } from './core.js';

package/dist/finalize/proposal.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Finalization proposal (DOCSYNC-001): the typed, strictly validated input an
+ * AI assistant or developer prepares. It carries the *content* of the
+ * finalization; MONOLITH decides whether and where it may be applied.
+ *
+ * Validation is structural and syntactic only. Whether the content is *true*
+ * (the summary matches the code) is the owner's judgement, taken when they
+ * approve the plan digest — never something this module claims to check.
+ */
+export declare const PROPOSAL_SCHEMA_VERSION = 1;
+/**
+ * What the Current Story section of active.md must hold before the transition.
+ * There is deliberately no "any": a proposal cannot switch the guard off and
+ * silently replace somebody else's active story. `contains` must name the
+ * story being finalized (checked in `parseProposal`).
+ */
+export type ExpectedCurrentStory = 'none' | {
+    contains: string;
+};
+export interface FinalizationProposal {
+    schemaVersion: 1;
+    story: {
+        /** Story identifier, e.g. `DOCSYNC-001` or `1.3`. Used as the idempotency key. */
+        id: string;
+        title: string;
+        /** Phase directory name under `memory/working/phases/`, e.g. `phase-1`. */
+        phase: string;
+        /** Text of the `## ` heading in story-index.md the entry belongs to. */
+        phaseHeading: string;
+        /** Capsule file base name (without `.md`), e.g. `story-docsync-001-finalization`. */
+        slug: string;
+        /** `YYYY-MM-DD`. Supplied by the caller: MONOLITH never invents a finalization date. */
+        date: string;
+    };
+    /** What the Current Story section of active.md must look like before the transition. */
+    expectedCurrentStory: ExpectedCurrentStory;
+    work: {
+        objective: string;
+        implementationSummary: string;
+        filesChanged: string[];
+        tests: string;
+        keyDecisions: string;
+        adrs: string[];
+        lessons: string;
+    };
+    /** One-paragraph summary for story-index.md. */
+    summary: string;
+    keyOutputs: string[];
+    history: {
+        phaseName: string;
+        decision: string;
+        build: string;
+    };
+    /** Complete replacement of HANDOFF.md. Optional: omitted means HANDOFF.md is not touched. */
+    handoff?: {
+        content: string;
+    };
+    /** Extra documentation edits; each path must be allowed by `monolith.config.json` `finalization`. */
+    docUpdates?: Array<{
+        path: string;
+        newContent: string;
+        reason: string;
+    }>;
+}
+export type ProposalParse = {
+    ok: true;
+    proposal: FinalizationProposal;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare const LIMITS: {
+    readonly idLen: 64;
+    readonly titleLen: 200;
+    readonly lineLen: 1000;
+    readonly blockLen: 20000;
+    readonly listItems: 200;
+    readonly docUpdates: 20;
+    readonly docBytes: number;
+};
+/**
+ * True when `text` holds `id` as a whole Story ID token (case-insensitive).
+ * Tokens are maximal runs of the Story ID alphabet [A-Za-z0-9._-]; trailing
+ * `.`/`_`/`-` (sentence punctuation) are dropped. So `S-1` is a token of
+ * "S-1 in progress" or "(S-1)", but never of "S-10", "XS-1", "1.10" or "11.1".
+ */
+export declare function hasStoryIdToken(text: string, id: string): boolean;
+export declare function validDate(s: string): boolean;
+/**
+ * Lexical validation of a project-relative document path (R4). Rejects
+ * absolute paths, `..`, backslashes, NUL, empty segments and VCS internals.
+ * Symlinks are NOT decided here: they are refused by the safe read/write
+ * primitives, which look at the real file system.
+ */
+export declare function validateRelPath(p: unknown): string | null;
+export declare function parseProposal(raw: unknown): ProposalParse;
+//# sourceMappingURL=proposal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proposal.d.ts","sourceRoot":"","sources":["../../src/finalize/proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,CAAC,CAAC;IACjB,KAAK,EAAE;QACL,kFAAkF;QAClF,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,2EAA2E;QAC3E,KAAK,EAAE,MAAM,CAAC;QACd,wEAAwE;QACxE,YAAY,EAAE,MAAM,CAAC;QACrB,qFAAqF;QACrF,IAAI,EAAE,MAAM,CAAC;QACb,wFAAwF;QACxF,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,wFAAwF;IACxF,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,IAAI,EAAE;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,6FAA6F;IAC7F,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,qGAAqG;IACrG,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3G,eAAO,MAAM,MAAM;;;;;;;;CAQT,CAAC;AAIX;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAGjE;AAaD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5C;AAuBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUzD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA2GzD"}

package/dist/finalize/proposal.js

@@ -0,0 +1,213 @@
+/**
+ * Finalization proposal (DOCSYNC-001): the typed, strictly validated input an
+ * AI assistant or developer prepares. It carries the *content* of the
+ * finalization; MONOLITH decides whether and where it may be applied.
+ *
+ * Validation is structural and syntactic only. Whether the content is *true*
+ * (the summary matches the code) is the owner's judgement, taken when they
+ * approve the plan digest — never something this module claims to check.
+ */
+export const PROPOSAL_SCHEMA_VERSION = 1;
+export const LIMITS = {
+    idLen: 64,
+    titleLen: 200,
+    lineLen: 1000,
+    blockLen: 20000,
+    listItems: 200,
+    docUpdates: 20,
+    docBytes: 1024 * 1024,
+};
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * True when `text` holds `id` as a whole Story ID token (case-insensitive).
+ * Tokens are maximal runs of the Story ID alphabet [A-Za-z0-9._-]; trailing
+ * `.`/`_`/`-` (sentence punctuation) are dropped. So `S-1` is a token of
+ * "S-1 in progress" or "(S-1)", but never of "S-10", "XS-1", "1.10" or "11.1".
+ */
+export function hasStoryIdToken(text, id) {
+    const want = id.toLowerCase();
+    return (text.match(/[A-Za-z0-9._-]+/g) ?? []).some((t) => t.replace(/[._-]+$/, '').toLowerCase() === want);
+}
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+const PHASE_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function noUnknown(obj, allowed, where, errors) {
+    for (const k of Object.keys(obj))
+        if (!allowed.includes(k))
+            errors.push(`${where}: unknown field "${k}".`);
+}
+export function validDate(s) {
+    const m = DATE_RE.exec(s);
+    if (m === null)
+        return false;
+    const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+    return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
+}
+function text(v, where, errors, opts) {
+    if (typeof v !== 'string') {
+        errors.push(`${where}: must be a string.`);
+        return '';
+    }
+    if (v.includes('\0'))
+        errors.push(`${where}: must not contain NUL.`);
+    if (!opts.allowEmpty && v.trim().length === 0)
+        errors.push(`${where}: must not be empty.`);
+    if (v.length > opts.max)
+        errors.push(`${where}: longer than ${opts.max} characters.`);
+    if (!opts.multiline && /[\r\n\u2028\u2029]/.test(v))
+        errors.push(`${where}: must be a single line.`);
+    return v;
+}
+function lines(v, where, errors) {
+    if (!Array.isArray(v)) {
+        errors.push(`${where}: must be an array of strings.`);
+        return [];
+    }
+    if (v.length > LIMITS.listItems)
+        errors.push(`${where}: more than ${LIMITS.listItems} items.`);
+    return v.map((x, i) => text(x, `${where}[${i}]`, errors, { multiline: false, max: LIMITS.lineLen }));
+}
+/**
+ * Lexical validation of a project-relative document path (R4). Rejects
+ * absolute paths, `..`, backslashes, NUL, empty segments and VCS internals.
+ * Symlinks are NOT decided here: they are refused by the safe read/write
+ * primitives, which look at the real file system.
+ */
+export function validateRelPath(p) {
+    if (typeof p !== 'string' || p.length === 0 || p.length > 260)
+        return 'path must be a non-empty string of at most 260 characters';
+    if (p.includes('\0') || p.includes('\\'))
+        return 'path must not contain NUL or backslashes';
+    if (p.startsWith('/') || /^[A-Za-z]:/.test(p))
+        return 'path must be relative to the project root';
+    const segs = p.split('/');
+    if (segs.some((s) => s === '' || s === '.' || s === '..'))
+        return 'path must not contain empty, "." or ".." segments';
+    // `.git` at ANY depth (nested repositories, submodule checkouts), any case
+    // (case-insensitive file systems), and trailing dot/space (Windows aliases).
+    if (segs.some((s) => /^\.git[. ]*$/i.test(s)) || segs.includes('node_modules'))
+        return 'path must not contain a .git (any case, any depth) or node_modules component';
+    return null;
+}
+export function parseProposal(raw) {
+    const errors = [];
+    if (!isObject(raw))
+        return { ok: false, errors: ['proposal must be a JSON object.'] };
+    noUnknown(raw, ['schemaVersion', 'story', 'expectedCurrentStory', 'work', 'summary', 'keyOutputs', 'history', 'handoff', 'docUpdates'], 'proposal', errors);
+    if (raw.schemaVersion !== PROPOSAL_SCHEMA_VERSION)
+        errors.push(`schemaVersion: must be ${PROPOSAL_SCHEMA_VERSION}.`);
+    const story = isObject(raw.story) ? raw.story : (errors.push('story: must be an object.'), {});
+    noUnknown(story, ['id', 'title', 'phase', 'phaseHeading', 'slug', 'date'], 'story', errors);
+    const id = text(story.id, 'story.id', errors, { multiline: false, max: LIMITS.idLen });
+    if (id && !ID_RE.test(id))
+        errors.push('story.id: must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}.');
+    const title = text(story.title, 'story.title', errors, { multiline: false, max: LIMITS.titleLen });
+    const phase = text(story.phase, 'story.phase', errors, { multiline: false, max: 32 });
+    if (phase && !PHASE_RE.test(phase))
+        errors.push('story.phase: must match [a-z0-9][a-z0-9-]{0,31}.');
+    const phaseHeading = text(story.phaseHeading, 'story.phaseHeading', errors, { multiline: false, max: LIMITS.titleLen });
+    if (phaseHeading.startsWith('#'))
+        errors.push('story.phaseHeading: give the heading text without leading "#".');
+    const slug = text(story.slug, 'story.slug', errors, { multiline: false, max: 100 });
+    if (slug && !SLUG_RE.test(slug))
+        errors.push('story.slug: must match [a-z0-9][a-z0-9._-]{0,99}.');
+    const date = text(story.date, 'story.date', errors, { multiline: false, max: 10 });
+    if (date && !validDate(date))
+        errors.push('story.date: must be a real date YYYY-MM-DD.');
+    let expected = 'none';
+    const e = raw.expectedCurrentStory;
+    if (e === 'none')
+        expected = e;
+    else if (isObject(e) && typeof e.contains === 'string' && e.contains.trim() !== '' && Object.keys(e).length === 1 && e.contains.length <= LIMITS.lineLen) {
+        expected = { contains: e.contains };
+        if (id && !hasStoryIdToken(e.contains, id)) {
+            errors.push(`expectedCurrentStory.contains: must contain the story id "${id}" as a whole token (not as part of a longer id), so the guard cannot match another story.`);
+        }
+    }
+    else if (e === 'any') {
+        errors.push('expectedCurrentStory: "any" is not accepted (it would allow replacing an unrelated active story). Use "none" or {"contains": "<text containing the story id>"}.');
+    }
+    else
+        errors.push('expectedCurrentStory: must be "none" or {"contains": "<text containing the story id>"}.');
+    const w = isObject(raw.work) ? raw.work : (errors.push('work: must be an object.'), {});
+    noUnknown(w, ['objective', 'implementationSummary', 'filesChanged', 'tests', 'keyDecisions', 'adrs', 'lessons'], 'work', errors);
+    const block = (v, name) => text(v, `work.${name}`, errors, { multiline: true, max: LIMITS.blockLen });
+    const work = {
+        objective: block(w.objective, 'objective'),
+        implementationSummary: block(w.implementationSummary, 'implementationSummary'),
+        filesChanged: lines(w.filesChanged, 'work.filesChanged', errors),
+        tests: block(w.tests, 'tests'),
+        keyDecisions: block(w.keyDecisions, 'keyDecisions'),
+        adrs: lines(w.adrs, 'work.adrs', errors),
+        lessons: block(w.lessons, 'lessons'),
+    };
+    const summary = text(raw.summary, 'summary', errors, { multiline: false, max: LIMITS.blockLen });
+    const keyOutputs = lines(raw.keyOutputs, 'keyOutputs', errors);
+    const h = isObject(raw.history) ? raw.history : (errors.push('history: must be an object.'), {});
+    noUnknown(h, ['phaseName', 'decision', 'build'], 'history', errors);
+    const history = {
+        phaseName: text(h.phaseName, 'history.phaseName', errors, { multiline: false, max: LIMITS.titleLen }),
+        decision: text(h.decision, 'history.decision', errors, { multiline: false, max: LIMITS.blockLen }),
+        build: text(h.build, 'history.build', errors, { multiline: false, max: LIMITS.lineLen }),
+    };
+    let handoff;
+    if (raw.handoff !== undefined) {
+        if (!isObject(raw.handoff))
+            errors.push('handoff: must be an object {"content": "..."}.');
+        else {
+            noUnknown(raw.handoff, ['content'], 'handoff', errors);
+            const content = text(raw.handoff.content, 'handoff.content', errors, { multiline: true, max: LIMITS.docBytes });
+            handoff = { content };
+        }
+    }
+    let docUpdates;
+    if (raw.docUpdates !== undefined) {
+        if (!Array.isArray(raw.docUpdates))
+            errors.push('docUpdates: must be an array.');
+        else {
+            if (raw.docUpdates.length > LIMITS.docUpdates)
+                errors.push(`docUpdates: more than ${LIMITS.docUpdates} entries.`);
+            docUpdates = [];
+            const seen = new Set();
+            raw.docUpdates.forEach((d, i) => {
+                const where = `docUpdates[${i}]`;
+                if (!isObject(d)) {
+                    errors.push(`${where}: must be an object.`);
+                    return;
+                }
+                noUnknown(d, ['path', 'newContent', 'reason'], where, errors);
+                const bad = validateRelPath(d.path);
+                if (bad !== null)
+                    errors.push(`${where}.path: ${bad}.`);
+                const path = typeof d.path === 'string' ? d.path : '';
+                if (seen.has(path))
+                    errors.push(`${where}.path: "${path}" is listed twice.`);
+                seen.add(path);
+                docUpdates.push({
+                    path,
+                    newContent: text(d.newContent, `${where}.newContent`, errors, { multiline: true, max: LIMITS.docBytes }),
+                    reason: text(d.reason, `${where}.reason`, errors, { multiline: false, max: LIMITS.lineLen }),
+                });
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const proposal = {
+        schemaVersion: 1,
+        story: { id, title, phase, phaseHeading, slug, date },
+        expectedCurrentStory: expected,
+        work,
+        summary,
+        keyOutputs,
+        history,
+    };
+    if (handoff)
+        proposal.handoff = handoff;
+    if (docUpdates && docUpdates.length > 0)
+        proposal.docUpdates = docUpdates;
+    return { ok: true, proposal };
+}

package/dist/ideas/cli.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `monolith idea ...` command handlers (IDEA-001A).
+ *
+ * Thin layer: strict flag parsing, store calls, output. No LLM, no network;
+ * `add` writes exactly one new file under `<monolithRoot>/memory/long-term/ideas/` and
+ * touches no other state (not `active.md`, not `state.json`); `list` and `show` write nothing.
+ */
+import type { Readable } from 'stream';
+interface AddFlags {
+    title?: string;
+    description?: string;
+    context?: string;
+    descriptionStdin?: boolean;
+}
+/** Strict: every flag needs a value, none may repeat, unknown flags and stray arguments are errors. */
+export declare function parseAddArgs(args: string[]): AddFlags;
+/**
+ * Read all of `input` as UTF-8, byte for byte (no trimming, BOM kept). Refuses
+ * more than STDIN_MAX_BYTES, invalid UTF-8 and a read error; nothing is
+ * interpreted. A terminal is refused instead of waiting for typed input.
+ */
+export declare function readStdinText(input?: Readable & {
+    isTTY?: boolean;
+}): Promise<string>;
+export declare function runIdeaAdd(args: string[], targetDir?: string, stdin?: Readable & {
+    isTTY?: boolean;
+}): Promise<void>;
+export declare function runIdeaList(args: string[], targetDir?: string): Promise<void>;
+export declare function runIdeaShow(args: string[], targetDir?: string): Promise<void>;
+/** Dispatcher used by the CLI entrypoint. */
+export declare function runIdeaCommand(args: string[], targetDir?: string): Promise<void>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/ideas/cli.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAiBvC,UAAU,QAAQ;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CA4BrD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB1G;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,EAAE,KAAK,GAAE,QAAQ,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhJ;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1F;AAiBD,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1F;AAED,6CAA6C;AAC7C,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F"}

package/dist/ideas/cli.js

@@ -0,0 +1,158 @@
+/* eslint-disable no-console */
+/**
+ * `monolith idea ...` command handlers (IDEA-001A).
+ *
+ * Thin layer: strict flag parsing, store calls, output. No LLM, no network;
+ * `add` writes exactly one new file under `<monolithRoot>/memory/long-term/ideas/` and
+ * touches no other state (not `active.md`, not `state.json`); `list` and `show` write nothing.
+ */
+import { reportWriteWarning } from '../root/index.js';
+import { addIdea, getIdea, ideaStore, listIdeas } from './store.js';
+import { IDEA_LIMITS, IdeaError } from './types.js';
+const ADD_USAGE = 'Usage: monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."]';
+/** UTF-8 needs at most 4 bytes per UTF-16 code unit's worth of text; anything larger cannot fit the description limit. */
+const STDIN_MAX_BYTES = IDEA_LIMITS.description * 4;
+const LIST_USAGE = 'Usage: monolith idea list';
+const SHOW_USAGE = 'Usage: monolith idea show <id>';
+/** Escape control characters so project-controlled text cannot forge terminal output. */
+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')}`);
+}
+const ADD_FLAGS = ['--title', '--description', '--context'];
+const STDIN_FLAG = '--description-stdin';
+const KNOWN_FLAGS = [...ADD_FLAGS, STDIN_FLAG];
+/** Strict: every flag needs a value, none may repeat, unknown flags and stray arguments are errors. */
+export function parseAddArgs(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (!KNOWN_FLAGS.includes(flag)) {
+            throw new IdeaError('IDEA_INVALID_INPUT', `Unexpected argument ${JSON.stringify(printable(flag))}.\n${ADD_USAGE}`);
+        }
+        if (flag === STDIN_FLAG) {
+            if (out.descriptionStdin)
+                throw new IdeaError('IDEA_INVALID_INPUT', `${flag} was given more than once.\n${ADD_USAGE}`);
+            out.descriptionStdin = true;
+            continue;
+        }
+        const key = flag.slice(2);
+        if (key in out)
+            throw new IdeaError('IDEA_INVALID_INPUT', `${flag} was given more than once.\n${ADD_USAGE}`);
+        const value = args[i + 1];
+        if (value === undefined || KNOWN_FLAGS.includes(value)) {
+            throw new IdeaError('IDEA_INVALID_INPUT', `${flag} needs a value.\n${ADD_USAGE}`);
+        }
+        out[key] = value;
+        i++;
+    }
+    if (out.descriptionStdin && out.description !== undefined) {
+        throw new IdeaError('IDEA_INVALID_INPUT', `--description and ${STDIN_FLAG} cannot be combined.\n${ADD_USAGE}`);
+    }
+    if (out.title === undefined || (out.description === undefined && !out.descriptionStdin)) {
+        throw new IdeaError('IDEA_INVALID_INPUT', `--title and --description (or ${STDIN_FLAG}) are required.\n${ADD_USAGE}`);
+    }
+    return out;
+}
+/**
+ * Read all of `input` as UTF-8, byte for byte (no trimming, BOM kept). Refuses
+ * more than STDIN_MAX_BYTES, invalid UTF-8 and a read error; nothing is
+ * interpreted. A terminal is refused instead of waiting for typed input.
+ */
+export async function readStdinText(input = process.stdin) {
+    if (input.isTTY) {
+        throw new IdeaError('IDEA_INVALID_INPUT', `${STDIN_FLAG} needs piped input, but stdin is a terminal.\n${ADD_USAGE}`);
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of input) {
+            const buf = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+            total += buf.length;
+            if (total > STDIN_MAX_BYTES) {
+                input.destroy();
+                throw new IdeaError('IDEA_INVALID_INPUT', `stdin is too large (more than ${STDIN_MAX_BYTES} bytes); nothing was written.`);
+            }
+            chunks.push(buf);
+        }
+    }
+    catch (err) {
+        if (err instanceof IdeaError)
+            throw err;
+        throw new IdeaError('IDEA_INVALID_INPUT', `could not read stdin: ${err.message}; nothing was written.`, { cause: err });
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+    }
+    catch (err) {
+        throw new IdeaError('IDEA_INVALID_INPUT', 'stdin is not valid UTF-8; nothing was written.', { cause: err });
+    }
+}
+export async function runIdeaAdd(args, targetDir = process.cwd(), stdin = process.stdin) {
+    const flags = parseAddArgs(args);
+    const description = flags.descriptionStdin ? await readStdinText(stdin) : flags.description;
+    const store = ideaStore(targetDir);
+    const { idea, path } = addIdea(store, { title: flags.title, description, context: flags.context }, { onWarning: (w) => reportWriteWarning(w) });
+    console.log(`Saved ${idea.id} [${idea.status}]: ${printable(idea.title)}`);
+    console.log(`  file: ${path}`);
+    console.log('Current task and focus are unchanged. Recall with `monolith idea list` / `monolith idea show ' + idea.id + '`.');
+}
+export async function runIdeaList(args, targetDir = process.cwd()) {
+    if (args.length > 0)
+        throw new IdeaError('IDEA_INVALID_INPUT', `Unexpected argument ${JSON.stringify(printable(args[0]))}.\n${LIST_USAGE}`);
+    const entries = listIdeas(ideaStore(targetDir));
+    if (entries.length === 0) {
+        console.log('No ideas. Capture one with `monolith idea add --title "..." --description "..."`.');
+        return;
+    }
+    console.log(`Ideas (${entries.length}):`);
+    let unreadable = 0;
+    for (const e of entries) {
+        if (e.ok) {
+            console.log(`  ${e.idea.id}  [${e.idea.status}]  ${printable(e.idea.title)}`);
+        }
+        else {
+            unreadable++;
+            console.log(`  ${e.id}  [unreadable]  ${printable(e.reason)}`);
+        }
+    }
+    if (unreadable > 0) {
+        console.error(`${unreadable} idea file(s) could not be read; they were left untouched. Inspect them with \`monolith idea show <id>\`.`);
+        process.exitCode = 2;
+    }
+}
+function formatIdea(i) {
+    const lines = [
+        `  id:         ${i.id}`,
+        `  title:      ${printable(i.title)}`,
+        `  status:     ${i.status}`,
+        `  createdAt:  ${i.createdAt}`,
+    ];
+    if (i.tags !== undefined && i.tags.length > 0)
+        lines.push(`  tags:       ${i.tags.map(printable).join(', ')}`);
+    lines.push('  context:    ' + (i.context === undefined ? '(none)' : ''));
+    if (i.context !== undefined)
+        lines.push(...i.context.split('\n').map((l) => `    ${l}`));
+    lines.push('  description:');
+    lines.push(...i.description.split('\n').map((l) => `    ${l}`));
+    return lines.join('\n');
+}
+export async function runIdeaShow(args, targetDir = process.cwd()) {
+    if (args.length !== 1)
+        throw new IdeaError('IDEA_INVALID_INPUT', SHOW_USAGE);
+    console.log(formatIdea(getIdea(ideaStore(targetDir), args[0])));
+}
+/** Dispatcher used by the CLI entrypoint. */
+export async function runIdeaCommand(args, targetDir = process.cwd()) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case 'add':
+            return runIdeaAdd(rest, targetDir);
+        case 'list':
+            return runIdeaList(rest, targetDir);
+        case 'show':
+            return runIdeaShow(rest, targetDir);
+        default:
+            throw new IdeaError('IDEA_INVALID_INPUT', `Unknown idea subcommand: ${sub === undefined ? '(none)' : JSON.stringify(printable(sub))}\n${ADD_USAGE}\n       ${LIST_USAGE.slice(7)}\n       ${SHOW_USAGE.slice(7)}`);
+    }
+}

package/dist/ideas/format.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Idea file format: Markdown with a small frontmatter block.
+ *
+ *   ---
+ *   type: idea
+ *   id: "IDEA-001"
+ *   title: "..."            (JSON string: any character survives a round trip)
+ *   status: inbox
+ *   createdAt: "2026-..."
+ *   context: "..."          (optional)
+ *   tags: ["a", "b"]        (optional)
+ *   ---
+ *
+ *   ## Description
+ *
+ *   <description, verbatim>
+ *
+ * Strings are written as JSON strings, which are also valid YAML double-quoted
+ * scalars, so ERG/Scriptorium read the file too. The reader additionally accepts
+ * a plain unquoted value, because a person edits these files by hand.
+ * The description is the body: no escaping, no trimming.
+ */
+import { type Idea, type NewIdea } from './types.js';
+export declare function isIdeaId(value: string): boolean;
+export declare function ideaNumber(id: string): number;
+export declare function formatIdeaId(n: number): string;
+/** `IDEA-007.md` -> `IDEA-007`; anything else (temp files, other documents) -> null. */
+export declare function ideaIdFromFileName(name: string): string | null;
+export declare function ideaFileName(id: string): string;
+/** Validates user input; returns it unchanged (content is never trimmed or rewritten). */
+export declare function validateNewIdea(input: NewIdea): NewIdea;
+export declare function serializeIdea(idea: Idea): string;
+/**
+ * Parse an idea file. `expectedId` is the id implied by the file name; a
+ * mismatch with the `id:` field is corruption, never silently "fixed".
+ */
+export declare function parseIdea(expectedId: string, text: string): Idea;
+//# sourceMappingURL=format.d.ts.map

package/dist/ideas/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/ideas/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAyC,KAAK,IAAI,EAAmB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAS7G,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG/C;AAaD,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAmBvD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAahD;AAqBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA0DhE"}