@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/http/server.js

@@ -0,0 +1,195 @@
+/**
+ * Secure read-only HTTP transport for Mission Control (UI-001B.2, ADR-010 G2).
+ *
+ * One endpoint, `GET /api/dashboard`, serves the existing `DashboardReadModel`
+ * exactly as `readDashboardModel(projectRoot)` returns it. This module is a
+ * transport only:
+ *  - it reads no file and imports no filesystem module; every byte of project
+ *    data arrives through `readDashboardModel` (ADR-014 safe read);
+ *  - it knows nothing about `state.json`, its schema or its physical layout, so
+ *    the Core storage can change (STATE-003) without touching this layer;
+ *  - the project root is fixed when the server starts and is never taken from a
+ *    request (query, body, header or cookie are not read for that purpose).
+ *
+ * With `options.assets` it also serves the built UI from memory (`monolith ui`);
+ * the API route, the Host/Origin checks and the loopback bind are unchanged.
+ *
+ * Security boundary (G2): bound to 127.0.0.1 only; `Host` allowlist (loopback
+ * name + the real port, against DNS rebinding); `Origin` checked when present
+ * and never reflected; no CORS headers at all; GET only; fixed response
+ * headers; bounded response size with no partial JSON; errors are fixed codes,
+ * never exception text or paths. Loopback is NOT treated as authentication.
+ *
+ * Source failures (absent / forbidden / corrupt / unreadable) are part of the
+ * DTO (`SourceReport`) and keep their Typed Read Model semantics: they are a
+ * valid 200 response carrying `data: null` and a typed code, never project
+ * content. Threat model (ADR-013): TM-A supported with limitations, TM-B
+ * partially supported, TM-C (concurrent adversarial mutation) NOT supported;
+ * dynamic TOCTOU is not closed here, nor by Core.
+ */
+import { createServer } from 'http';
+import { isAbsolute } from 'path';
+import { readDashboardModel } from '../readmodel/index.js';
+export const DASHBOARD_PATH = '/api/dashboard';
+/** The only bind address; there is deliberately no option to change it. */
+export const LOOPBACK_HOST = '127.0.0.1';
+/**
+ * Hard ceiling for one serialized response. The Core read limits (state 16 MiB,
+ * active.md/roadmap 256 KiB) are protective ceilings of their own and can exceed
+ * it; an over-limit DTO is refused whole, never truncated.
+ */
+export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const ERROR_STATUS = {
+    HOST_NOT_ALLOWED: 403,
+    ORIGIN_NOT_ALLOWED: 403,
+    NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
+    RESPONSE_TOO_LARGE: 500,
+    INTERNAL_ERROR: 500,
+};
+const ERROR_KIND = {
+    HOST_NOT_ALLOWED: 'security',
+    ORIGIN_NOT_ALLOWED: 'security',
+    NOT_FOUND: 'request',
+    METHOD_NOT_ALLOWED: 'request',
+    RESPONSE_TOO_LARGE: 'dashboard',
+    INTERNAL_ERROR: 'internal',
+};
+function send(res, status, body, extra = {}) {
+    const buf = Buffer.from(body, 'utf8');
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': String(buf.length),
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+        'Content-Security-Policy': "default-src 'none'",
+        ...extra,
+    });
+    res.end(buf);
+}
+/** CSP of the UI document and its assets: self-hosted code only, no framing, no form posts. */
+const UI_CSP = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; " +
+    "font-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+function sendAsset(res, body, contentType) {
+    res.writeHead(200, {
+        'Content-Type': contentType,
+        'Content-Length': String(body.length),
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+        'Content-Security-Policy': UI_CSP,
+        'Referrer-Policy': 'no-referrer',
+        'Cross-Origin-Resource-Policy': 'same-origin',
+    });
+    res.end(body);
+}
+function sendError(res, code) {
+    const body = { error: { kind: ERROR_KIND[code], code } };
+    // An unread request body must not keep the connection busy.
+    const extra = { Connection: 'close' };
+    if (code === 'METHOD_NOT_ALLOWED')
+        extra.Allow = 'GET';
+    send(res, ERROR_STATUS[code], JSON.stringify(body), extra);
+}
+function single(h) {
+    return typeof h === 'string' ? h : undefined;
+}
+/**
+ * Node exposes only the first `Host` in `req.headers`, so duplicates must be
+ * counted on the raw header list (names are case-insensitive; values are
+ * ignored here and never echoed).
+ */
+function hostHeaderCount(rawHeaders) {
+    let count = 0;
+    for (let i = 0; i < rawHeaders.length; i += 2) {
+        if (rawHeaders[i].toLowerCase() === 'host')
+            count++;
+    }
+    return count;
+}
+/** Path of the request target without its query; the query is never interpreted. */
+function pathOf(target) {
+    if (target === undefined)
+        return '';
+    const q = target.indexOf('?');
+    return q === -1 ? target : target.slice(0, q);
+}
+export async function startDashboardServer(options) {
+    const { projectRoot } = options;
+    if (typeof projectRoot !== 'string' || !isAbsolute(projectRoot)) {
+        throw new TypeError('projectRoot must be an absolute path');
+    }
+    const maxBytes = options.maxResponseBytes ?? MAX_RESPONSE_BYTES;
+    let allowedHosts = new Set();
+    let allowedOrigins = new Set();
+    function handle(req, res) {
+        // 1. Security preconditions, before anything about the route is revealed.
+        // Exactly one Host: a duplicate is ambiguous (proxies may pick another one).
+        const host = single(req.headers.host)?.toLowerCase();
+        if (hostHeaderCount(req.rawHeaders) !== 1 || host === undefined || !allowedHosts.has(host))
+            return sendError(res, 'HOST_NOT_ALLOWED');
+        if (req.headers.origin !== undefined && !allowedOrigins.has(single(req.headers.origin)?.toLowerCase() ?? '')) {
+            return sendError(res, 'ORIGIN_NOT_ALLOWED');
+        }
+        // 2. Route and method. Exact match only: no trailing slash, no decoding.
+        const path = pathOf(req.url);
+        if (path !== DASHBOARD_PATH) {
+            const asset = options.assets?.get(path === '/' ? '/index.html' : path);
+            if (asset === undefined)
+                return sendError(res, 'NOT_FOUND');
+            if (req.method !== 'GET')
+                return sendError(res, 'METHOD_NOT_ALLOWED');
+            return sendAsset(res, asset.body, asset.contentType);
+        }
+        if (req.method !== 'GET')
+            return sendError(res, 'METHOD_NOT_ALLOWED');
+        // 3. The DTO, whole or not at all.
+        let body;
+        try {
+            body = JSON.stringify(readDashboardModel(projectRoot));
+        }
+        catch {
+            return sendError(res, 'INTERNAL_ERROR');
+        }
+        if (Buffer.byteLength(body, 'utf8') > maxBytes)
+            return sendError(res, 'RESPONSE_TOO_LARGE');
+        send(res, 200, body);
+    }
+    const server = createServer((req, res) => {
+        try {
+            handle(req, res);
+        }
+        catch {
+            if (!res.headersSent)
+                sendError(res, 'INTERNAL_ERROR');
+            else
+                res.destroy();
+        }
+    });
+    server.requestTimeout = 10_000;
+    server.headersTimeout = 5_000;
+    const port = await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port ?? 0, LOOPBACK_HOST, () => {
+            server.off('error', reject);
+            const addr = server.address();
+            if (addr === null || typeof addr === 'string')
+                reject(new Error('unexpected listen address'));
+            else
+                resolve(addr.port);
+        });
+    }).catch((err) => {
+        server.close();
+        throw err;
+    });
+    allowedHosts = new Set([`${LOOPBACK_HOST}:${port}`, `localhost:${port}`]);
+    allowedOrigins = new Set([`http://${LOOPBACK_HOST}:${port}`, `http://localhost:${port}`]);
+    return {
+        host: LOOPBACK_HOST,
+        port,
+        url: `http://${LOOPBACK_HOST}:${port}`,
+        close: () => new Promise((resolve, reject) => {
+            server.close((err) => (err ? reject(err) : resolve()));
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/http/ui-assets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Loader for the built Mission Control UI (`dist/ui`), used by `monolith ui`.
+ *
+ * The HTTP transport (`server.ts`) imports no filesystem module on purpose, so
+ * the static files are read here, once, at startup, into memory. The server
+ * then serves them by exact key: a request path is never joined to a directory,
+ * so path traversal has nothing to traverse.
+ *
+ * What is accepted: regular files only (no symlink, no special file, one link),
+ * a fixed extension allowlist, a bounded directory depth, file count and size.
+ * Anything else is skipped, except that a missing or unsafe `index.html` is an
+ * error. Assets are read once; later changes on disk are not picked up.
+ */
+import type { UiAssets } from './server.js';
+export type UiAssetsErrorCode = 'UI_BUILD_MISSING' | 'UI_BUILD_UNSAFE' | 'UI_BUILD_TOO_LARGE';
+export declare class UiAssetsError extends Error {
+    readonly code: UiAssetsErrorCode;
+    constructor(code: UiAssetsErrorCode, message: string);
+}
+/** Reads `dir` (the built UI) into memory. Throws `UiAssetsError` if there is no usable `index.html`. */
+export declare function loadUiAssets(dir: string): UiAssets;
+//# sourceMappingURL=ui-assets.d.ts.map

package/dist/http/ui-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-assets.d.ts","sourceRoot":"","sources":["../../src/http/ui-assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAW,QAAQ,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAE9F,qBAAa,aAAc,SAAQ,KAAK;IAC1B,QAAQ,CAAC,IAAI,EAAE,iBAAiB;gBAAvB,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM;CAI9D;AAiCD,yGAAyG;AACzG,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAwClD"}

package/dist/http/ui-assets.js

@@ -0,0 +1,100 @@
+/**
+ * Loader for the built Mission Control UI (`dist/ui`), used by `monolith ui`.
+ *
+ * The HTTP transport (`server.ts`) imports no filesystem module on purpose, so
+ * the static files are read here, once, at startup, into memory. The server
+ * then serves them by exact key: a request path is never joined to a directory,
+ * so path traversal has nothing to traverse.
+ *
+ * What is accepted: regular files only (no symlink, no special file, one link),
+ * a fixed extension allowlist, a bounded directory depth, file count and size.
+ * Anything else is skipped, except that a missing or unsafe `index.html` is an
+ * error. Assets are read once; later changes on disk are not picked up.
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync } from 'fs';
+import { join, extname } from 'path';
+export class UiAssetsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'UiAssetsError';
+    }
+}
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.webp': 'image/webp',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+};
+const MAX_DEPTH = 3;
+const MAX_FILES = 200;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+function readRegular(abs) {
+    // lstat first so a symlink is refused rather than followed.
+    const st = lstatSync(abs);
+    if (!st.isFile() || st.nlink !== 1)
+        return null;
+    if (st.size > MAX_FILE_BYTES)
+        throw new UiAssetsError('UI_BUILD_TOO_LARGE', `UI build file is larger than ${MAX_FILE_BYTES} bytes.`);
+    const fd = openSync(abs, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const fst = fstatSync(fd);
+        if (!fst.isFile() || fst.dev !== st.dev || fst.ino !== st.ino)
+            return null;
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Reads `dir` (the built UI) into memory. Throws `UiAssetsError` if there is no usable `index.html`. */
+export function loadUiAssets(dir) {
+    const assets = new Map();
+    let total = 0;
+    const walk = (abs, rel, depth) => {
+        for (const name of readdirSync(abs).sort()) {
+            const childAbs = join(abs, name);
+            const childRel = `${rel}/${name}`;
+            const st = lstatSync(childAbs);
+            if (st.isDirectory()) {
+                if (depth < MAX_DEPTH)
+                    walk(childAbs, childRel, depth + 1);
+                continue;
+            }
+            const contentType = CONTENT_TYPES[extname(name).toLowerCase()];
+            if (contentType === undefined)
+                continue;
+            const body = readRegular(childAbs);
+            if (body === null)
+                continue;
+            total += body.length;
+            if (assets.size >= MAX_FILES || total > MAX_TOTAL_BYTES) {
+                throw new UiAssetsError('UI_BUILD_TOO_LARGE', 'UI build has too many or too large files.');
+            }
+            assets.set(childRel, { body, contentType });
+        }
+    };
+    try {
+        if (!lstatSync(dir).isDirectory())
+            throw new UiAssetsError('UI_BUILD_MISSING', 'UI build directory is not a directory.');
+        walk(dir, '', 0);
+    }
+    catch (err) {
+        if (err instanceof UiAssetsError)
+            throw err;
+        if (err.code === 'ENOENT') {
+            throw new UiAssetsError('UI_BUILD_MISSING', 'UI build directory does not exist.');
+        }
+        throw new UiAssetsError('UI_BUILD_UNSAFE', 'UI build directory could not be read safely.');
+    }
+    if (!assets.has('/index.html')) {
+        throw new UiAssetsError('UI_BUILD_MISSING', 'UI build has no index.html.');
+    }
+    return assets;
+}

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"}