agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/cli/commands/state/todo.js

@@ -1,25 +1,10 @@
-/**
- * `state todo` query (TODO.md).
- *
- * Reads TODO.md, partitions entries by severity band (using the
- * protocol glyphs as the section heading), and reports each entry
- * with its severity, status, and description. Supports both the
- * legacy structured YAML shape and the current markdown layout.
- */
-import fs from "node:fs";
-import { emitStateStructured, extractEntries, filterByFieldValue, formatEntry, loadArtifact, printStatusCounts, sourceMetadata, statusCounts, structuredState, } from "../../stateQuery.js";
-import { artifactPath } from "../../appContext.js";
-import { isResolvedTodoMarkdownStatus, parseTodoMarkdownListItem } from "../../todoMarkdown.js";
-import { out, err } from "./shared.js";
-const TODO_SEVERITY_ORDER_KEYS = ["critical", "degraded", "warning", "normal", "info", "annoying"];
-const TODO_SEV_GLYPHS = {
-    critical: "⇶",
-    degraded: "⇉",
-    warning: "⇉",
-    normal: "→",
-    info: "⇢",
-    annoying: "⇢",
-};
+import { emitStructured } from "../../structured.js";
+import { TODO_SEVERITY_ORDER_KEYS } from "../../todoSeverity.js";
+import { renderTodoPublicRecord } from "../../todoMarkdown.js";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { listTodoDocsEntities } from "../../../state/todoDocsEntities.js";
+import YAML from "yaml";
+import { err, out } from "./shared.js";
 export function normalizeSeverity(value, deflt = "normal") {
     const text = String(value || deflt).toLowerCase();
     for (const key of TODO_SEVERITY_ORDER_KEYS) {
@@ -28,94 +13,30 @@ export function normalizeSeverity(value, deflt = "normal") {
     }
     return deflt;
 }
-export function queryTodo(args, schemas, io, openOnly = false) {
-    const o = out(io);
-    const info = schemas.todo ?? { path: "TODO.md", record: undefined, schema: {}, fields: {} };
-    const todoPath = artifactPath(info, "todo");
-    const severity = args.severity ?? null;
-    const status = args.status ?? null;
+export function queryTodo(args, _schemas, io, openOnly = false) {
+    const output = out(io);
     const format = args.format ?? "text";
-    if (!fs.existsSync(todoPath)) {
-        if (format !== "text") {
-            return emitStateStructured("todo", structuredState("todo", [], sourceMetadata("todo", todoPath), {
-                filters: { severity, status },
-            }), format, args.fields, o, err(io));
-        }
-        return 0;
-    }
-    const data = loadArtifact(todoPath);
-    let entries = extractEntries(data);
-    if (entries.length > 0) {
-        if (severity)
-            entries = filterByFieldValue(entries, "severity", severity);
-        if (status)
-            entries = filterByFieldValue(entries, "status", status);
-        if (openOnly) {
-            entries = entries.filter((entry) => !["done", "closed", "resolved"].includes(String(entry.status ?? "open").toLowerCase()));
-        }
-        if (format !== "text") {
-            return emitStateStructured("todo", structuredState("todo", entries, sourceMetadata("todo", todoPath), {
-                filters: { severity, status, open_only: openOnly || null },
-            }), format, args.fields, o, err(io));
-        }
-        printStatusCounts("TODO status", statusCounts(entries), o);
-        for (const entry of entries) {
-            const line = formatEntry(entry, ["severity", "status", "description", "title"]);
-            if (line)
-                o(line + "\n");
-        }
-        return 0;
-    }
-    const text = fs.readFileSync(todoPath, "utf8");
-    const marker = severity ? TODO_SEV_GLYPHS[severity.toLowerCase()] ?? severity : null;
-    let currentSection = null;
-    const markdownEntries = [];
-    for (const rawLine of text.split(/\r\n|\r|\n/)) {
-        const sline = rawLine.trim();
-        if (sline.startsWith("## ")) {
-            const section = sline.slice(3).trim();
-            if (section.toLowerCase().includes("resolved")) {
-                currentSection = null;
-                continue;
+    try {
+        const response = listTodoDocsEntities(process.cwd(), "todo", args.limit ?? undefined, undefined, {
+            ...(args.severity ? { severity: args.severity } : {}),
+            ...(args.status ? { status: args.status } : {}),
+            ...(openOnly ? { status: "open" } : {}),
+        }, { format });
+        if (format === "json" || format === "yaml")
+            emitStructured(response, format, output);
+        else
+            for (const entry of response.entries) {
+                output(`[${entry.record.severity}] ${entry.id} ${entry.record.status}: ${renderTodoPublicRecord(entry.record)}\n`);
             }
-            currentSection = section;
-            continue;
-        }
-        if (currentSection === null)
-            continue;
-        const parsed = parseTodoMarkdownListItem(sline);
-        if (!parsed)
-            continue;
-        if (marker && !currentSection.includes(marker))
-            continue;
-        const itemStatus = parsed.status;
-        if (openOnly && isResolvedTodoMarkdownStatus(itemStatus))
-            continue;
-        if (status) {
-            const want = status.toLowerCase();
-            const have = itemStatus.toLowerCase();
-            if (want === "open" || want === "todo") {
-                if (isResolvedTodoMarkdownStatus(have))
-                    continue;
-            }
-            else if (have !== want) {
-                continue;
-            }
-        }
-        markdownEntries.push({
-            severity: normalizeSeverity(currentSection),
-            status: itemStatus,
-            description: parsed.description,
-            section: currentSection,
-        });
-        if (format === "text")
-            o(`[${currentSection}] ${parsed.description}\n`);
+        return 0;
     }
-    if (format !== "text") {
-        return emitStateStructured("todo", structuredState("todo", markdownEntries, sourceMetadata("todo", todoPath), {
-            filters: { severity, status, open_only: openOnly || null },
-        }), format, args.fields, o, err(io));
+    catch (error) {
+        if (!(error instanceof StateRetrievalFailure))
+            throw error;
+        if (format === "json" || format === "yaml")
+            emitStructured(error.body, format, output);
+        else
+            err(io)(YAML.stringify(error.body));
+        return error.exitCode;
     }
-    return 0;
 }
-//# sourceMappingURL=todo.js.map

package/dist/cli/commands/state/write.js

@@ -0,0 +1,433 @@
+import path from "node:path";
+import fs from "node:fs";
+import { emitInvalidInput } from "../../errors.js";
+import { emitStructured } from "../../structured.js";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { normalizeArtifactProtocolId, VALIDATE_ARTIFACT_PROTOCOL_IDS, } from "../../../registries/artifactProtocolIds.js";
+import { buildExplain, buildExplainAll, assertMutationGrammarParity, exampleFor, executeStateWrite, isWritableArtifact, loadStructuredInput, operationSpec, projectedFields, renderExplainText, StateWriteInputError, verbsForArtifact, WRITABLE_ARTIFACTS, } from "../../../state/write/index.js";
+function formatFromArgv(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--format" && argv[i + 1] === "json")
+            return "json";
+        if (argv[i] === "--format=json")
+            return "json";
+    }
+    return "text";
+}
+function invalid(body) {
+    throw new StateWriteInputError(body);
+}
+function emitRetrievalFailure(error, format, io) {
+    if (format === "json") {
+        emitStructured(error.body, "json", io.out ?? ((text) => process.stdout.write(text)));
+    }
+    else {
+        const detail = error.body.error;
+        (io.err ?? ((text) => process.stderr.write(text)))([
+            `Error: ${detail.message}`,
+            `Syntax: ${detail.syntax}`,
+            `Example: ${detail.example}`,
+            `Recovery: ${detail.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+function setNested(target, field, value) {
+    const parts = field.split(".");
+    let cursor = target;
+    for (const part of parts.slice(0, -1)) {
+        if (!cursor[part] || typeof cursor[part] !== "object" || Array.isArray(cursor[part]))
+            cursor[part] = {};
+        cursor = cursor[part];
+    }
+    cursor[parts.at(-1)] = value;
+}
+function hasNested(target, field) {
+    let value = target;
+    for (const part of field.split(".")) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        if (!(part in value))
+            return false;
+        value = value[part];
+    }
+    return true;
+}
+function readFlag(argv, index) {
+    const token = argv[index];
+    const equals = token.indexOf("=");
+    if (equals > 0)
+        return { name: token.slice(0, equals), value: token.slice(equals + 1), consumed: 1 };
+    return { name: token, value: argv[index + 1] ?? null, consumed: 2 };
+}
+function converted(field, raw) {
+    if (field.kind === "boolean") {
+        if (raw !== "true" && raw !== "false")
+            invalid({
+                class: "invalid_choice",
+                message: `argument ${field.flag}: expected true or false, got '${raw}'`,
+                valid_values: ["true", "false"],
+            });
+        return raw === "true";
+    }
+    if (field.kind === "integer") {
+        const number = Number(raw);
+        if (!Number.isInteger(number))
+            invalid({
+                class: "invalid_int",
+                message: `argument ${field.flag}: invalid int value: '${raw}'`,
+                syntax: `${field.flag} N`,
+            });
+        return number;
+    }
+    if (field.kind === "date" && !/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        invalid({
+            class: "invalid_format",
+            message: `argument ${field.flag}: expected YYYY-MM-DD, got '${raw}'`,
+            syntax: `${field.flag} YYYY-MM-DD`,
+        });
+    }
+    if (field.kind === "datetime" && !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(raw)) {
+        invalid({
+            class: "invalid_format",
+            message: `argument ${field.flag}: expected YYYY-MM-DD HH:MM, got '${raw}'`,
+            syntax: `${field.flag} "YYYY-MM-DD HH:MM"`,
+        });
+    }
+    if (field.validValues && !field.validValues.includes(raw)) {
+        const privacySafe = field.field.startsWith("glossary_caveat.");
+        invalid({
+            class: "invalid_choice",
+            message: privacySafe
+                ? `argument ${field.flag}: invalid bounded glossary caveat value`
+                : `argument ${field.flag}: invalid choice: '${raw}' (choose from ${field.validValues.map((v) => `'${v}'`).join(", ")})`,
+            valid_values: field.validValues,
+        });
+    }
+    return raw;
+}
+function artifactOrReject(raw) {
+    const normalized = normalizeArtifactProtocolId(raw);
+    if (normalized === null) {
+        invalid({
+            class: "unsupported_target",
+            message: `unsupported artifact "${raw}"; valid artifact_id values: ${VALIDATE_ARTIFACT_PROTOCOL_IDS.join(", ")}`,
+            valid_values: [...WRITABLE_ARTIFACTS],
+        });
+    }
+    if (!isWritableArtifact(normalized)) {
+        invalid({
+            class: "unsupported_target",
+            message: `artifact "${normalized}" is read-only through the state writer`,
+            valid_values: [...WRITABLE_ARTIFACTS],
+            example: "agentera state progress append --input progress.yaml --format json",
+        });
+    }
+    return normalized;
+}
+function specOrReject(artifact, verb) {
+    const spec = operationSpec(artifact, verb);
+    if (!spec) {
+        const retrievalVerbs = artifact === "plan" ? ["list", "get", "tasks"] : artifact === "experiments" ? ["list", "get"] : [];
+        invalid({
+            class: "invalid_choice",
+            message: `verb "${verb}" does not apply to ${artifact}`,
+            valid_values: [...retrievalVerbs, ...verbsForArtifact(artifact)],
+            example: artifact === "experiments"
+                ? "agentera state experiments list --objective OBJECTIVE_ID --format json"
+                : `agentera state ${artifact} ${artifact === "plan" ? "list --format json" : "explain --format json"}`,
+        });
+    }
+    return spec;
+}
+function parseWrite(artifactRaw, argv) {
+    const artifact = artifactOrReject(artifactRaw);
+    const verb = argv[0];
+    if (!verb)
+        invalid({
+            class: "missing_argument",
+            message: `write verb is required for ${artifact}`,
+            valid_values: verbsForArtifact(artifact),
+        });
+    const spec = specOrReject(artifact, verb);
+    let initialProjectRoot = process.cwd();
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--project" && argv[index + 1])
+            initialProjectRoot = path.resolve(argv[index + 1]);
+        else if (token.startsWith("--project="))
+            initialProjectRoot = path.resolve(token.slice("--project=".length));
+    }
+    const fields = projectedFields(spec);
+    const byFlag = new Map(fields.map((field) => [field.flag, field]));
+    const values = {};
+    const callerPayload = {};
+    const occurrences = new Map();
+    let format = "text";
+    let projectRoot = initialProjectRoot;
+    let dryRun = false;
+    let force = false;
+    let inputSource = null;
+    for (let i = 1; i < argv.length;) {
+        const token = argv[i];
+        if (!token.startsWith("--"))
+            invalid({ class: "unrecognized_argument", message: `unrecognized arguments: ${token}` });
+        if (token === "--dry-run") {
+            dryRun = true;
+            i += 1;
+            continue;
+        }
+        if (token === "--force") {
+            force = true;
+            i += 1;
+            continue;
+        }
+        const bareBoolean = byFlag.get(token);
+        if (bareBoolean?.kind === "boolean") {
+            if ((occurrences.get(token) ?? 0) > 0)
+                invalid({ class: "mutually_exclusive", message: `${token} may only be supplied once` });
+            occurrences.set(token, 1);
+            setNested(values, bareBoolean.field, true);
+            setNested(callerPayload, bareBoolean.field, true);
+            i += 1;
+            continue;
+        }
+        const parsed = readFlag(argv, i);
+        if (parsed.value === null || parsed.value.startsWith("--"))
+            invalid({
+                class: "missing_argument",
+                message: `${parsed.name} requires a value`,
+                syntax: `${parsed.name} VALUE`,
+            });
+        i += parsed.consumed;
+        if (parsed.name === "--format") {
+            if (parsed.value !== "text" && parsed.value !== "json")
+                invalid({
+                    class: "invalid_choice",
+                    message: `argument --format: invalid choice: '${parsed.value}' (choose from 'text', 'json')`,
+                    valid_values: ["text", "json"],
+                });
+            format = parsed.value;
+            continue;
+        }
+        if (parsed.name === "--project") {
+            projectRoot = path.resolve(parsed.value);
+            continue;
+        }
+        if (parsed.name === "--input") {
+            if (inputSource !== null)
+                invalid({ class: "mutually_exclusive", message: "--input may only be supplied once" });
+            inputSource = parsed.value;
+            continue;
+        }
+        if (artifact === "decisions" && verb === "append" && parsed.name === "--number") {
+            invalid({
+                class: "unrecognized_argument",
+                message: "--number is assigned by the CLI on append and cannot be supplied",
+                example: exampleFor(artifact, verb),
+            });
+        }
+        const field = byFlag.get(parsed.name);
+        if (!field) {
+            if (spec.inputRoot && inputSource)
+                invalid({
+                    class: "mutually_exclusive",
+                    message: `--input cannot be combined with ${parsed.name}`,
+                    syntax: "--input PATH",
+                    example: exampleFor(artifact, verb),
+                });
+            invalid({
+                class: "unrecognized_argument",
+                message: `unrecognized arguments: ${parsed.name}`,
+                example: exampleFor(artifact, verb),
+            });
+        }
+        const count = (occurrences.get(parsed.name) ?? 0) + 1;
+        occurrences.set(parsed.name, count);
+        if (!field.repeatable && count > 1) {
+            const message = parsed.name === "--alternative-chosen"
+                ? `exactly one alternative must be chosen (DV3); received ${count} --alternative-chosen flags`
+                : `${parsed.name} may only be supplied once`;
+            invalid({ class: "mutually_exclusive", message });
+        }
+        const value = converted(field, parsed.value);
+        if (field.repeatable) {
+            const current = mappingPath(values, field.field) ?? [];
+            setNested(values, field.field, [...current, value]);
+            setNested(callerPayload, field.field, [...current, value]);
+        }
+        else {
+            setNested(values, field.field, value);
+            setNested(callerPayload, field.field, value);
+        }
+    }
+    if (force && !spec.allowForce)
+        invalid({
+            class: "unrecognized_argument",
+            message: `--force does not apply to ${artifact} ${verb}`,
+        });
+    if (inputSource && !spec.inputRoot)
+        invalid({
+            class: "mutually_exclusive",
+            message: `${artifact} ${verb} accepts field flags, not --input`,
+            example: exampleFor(artifact, verb),
+        });
+    if (spec.inputRoot && !inputSource && !spec.inputOptional)
+        invalid({
+            class: "missing_argument",
+            message: `--input is required for ${artifact} ${verb}`,
+            syntax: "--input PATH",
+            example: exampleFor(artifact, verb),
+        });
+    const selectorFields = new Set(spec.fields.filter((field) => spec.selectors.includes(field.flag)).map((field) => field.field));
+    const correctionApplyFields = artifact === "todo" && verb === "correct-owners"
+        ? new Set(["effect_sha256", "confirmed"])
+        : new Set();
+    if (spec.inputRoot && Object.keys(values).some((field) => !selectorFields.has(field) && !correctionApplyFields.has(field)))
+        invalid({
+            class: "mutually_exclusive",
+            message: `--input cannot be combined with field flags for ${artifact} ${verb}`,
+        });
+    for (const field of fields.filter((candidate) => candidate.required)) {
+        if (mappingPath(values, field.field) === undefined) {
+            invalid({
+                class: "missing_argument",
+                message: `${field.flag} is required for ${artifact} ${verb}`,
+                valid_values: field.validValues,
+                syntax: `${field.flag} VALUE`,
+                example: exampleFor(artifact, verb),
+            });
+        }
+    }
+    if (artifact === "decisions" && (verb === "update" || verb === "amend")) {
+        const id = mappingPath(values, "id");
+        const number = mappingPath(values, "number");
+        if (number !== undefined)
+            invalid({ class: "unrecognized_argument", message: "numeric decision selectors are unavailable in entity mode; use --id ID" });
+        if (id === undefined)
+            invalid({ class: "missing_argument", message: `--id is required for decisions ${verb} in entity mode` });
+        if (verb === "amend" && mappingPath(values, "base_sha256") === undefined)
+            invalid({ class: "missing_argument", message: "--base-sha256 is required for decisions amend in entity mode" });
+    }
+    if (artifact === "plan" && verb !== "create") {
+        const taskVerb = ["update", "set-status", "supersede", "record-evaluation"].includes(verb);
+        const id = mappingPath(values, "id");
+        if (taskVerb && id === undefined)
+            invalid({ class: "missing_argument", message: `--id is required for plan ${verb} in entity mode` });
+    }
+    return { artifact, spec, format, projectRoot, dryRun, force, values, callerPayload, inputSource };
+}
+function mappingPath(entry, field) {
+    let value = entry;
+    for (const part of field.split(".")) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+function explainArgs(argv) {
+    let format = "text";
+    let project = process.cwd();
+    let verb = null;
+    let all = false;
+    for (let i = 1; i < argv.length;) {
+        if (argv[i] === "--all") {
+            all = true;
+            i += 1;
+            continue;
+        }
+        const parsed = readFlag(argv, i);
+        if (parsed.value === null || parsed.value.startsWith("--"))
+            invalid({ class: "missing_argument", message: `${parsed.name} requires a value` });
+        i += parsed.consumed;
+        if (parsed.name === "--format") {
+            if (parsed.value !== "text" && parsed.value !== "json")
+                invalid({
+                    class: "invalid_choice",
+                    message: `argument --format: invalid choice: '${parsed.value}' (choose from 'text', 'json')`,
+                    valid_values: ["text", "json"],
+                });
+            format = parsed.value;
+        }
+        else if (parsed.name === "--project")
+            project = path.resolve(parsed.value);
+        else if (parsed.name === "--verb")
+            verb = parsed.value;
+        else
+            invalid({
+                class: "unrecognized_argument",
+                message: `unrecognized arguments: ${parsed.name}`,
+            });
+    }
+    if (all && verb)
+        invalid({ class: "mutually_exclusive", message: "--all cannot be combined with --verb" });
+    return { format, project, verb, all };
+}
+export function runStateWrite(artifactRaw, argv, io) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    const err = io.err ?? ((text) => process.stderr.write(text));
+    const detectedFormat = formatFromArgv(argv);
+    try {
+        const artifact = artifactOrReject(artifactRaw);
+        assertMutationGrammarParity();
+        if (argv[0] === "explain") {
+            const args = explainArgs(argv);
+            const explanation = args.all
+                ? buildExplainAll(artifact, args.project)
+                : buildExplain(artifact, args.project, args.verb);
+            if (args.format === "json")
+                out(JSON.stringify(explanation, null, 2) + "\n");
+            else
+                out(renderExplainText(explanation));
+            return 0;
+        }
+        const parsed = parseWrite(artifactRaw, argv);
+        let input = null;
+        if (parsed.inputSource) {
+            try {
+                input = loadStructuredInput(parsed.inputSource, io.stdin ?? (() => fsStdin()), parsed.spec.inputMaxBytes);
+            }
+            catch (error) {
+                const message = error.message;
+                invalid({
+                    class: message.startsWith("input file") ? "unsupported_target" : message.includes("UTF-8 limit") ? "schema_violation" : "invalid_format",
+                    message,
+                    syntax: "--input PATH",
+                    example: exampleFor(parsed.artifact, parsed.spec.verb),
+                    ...(message.includes("UTF-8 limit") ? { violations: [message] } : {}),
+                });
+            }
+            for (const owned of parsed.spec.cliOwnedFields ?? []) {
+                if (hasNested(input, owned))
+                    invalid({
+                        class: "schema_violation",
+                        message: `${parsed.artifact} ${parsed.spec.verb} assigns ${owned}; remove '${owned}' from the input document`,
+                        violations: [`CLI-owned field: ${owned}`],
+                    });
+            }
+            parsed.callerPayload = structuredClone(input);
+        }
+        const envelope = executeStateWrite({ ...parsed, input });
+        if (parsed.format === "json")
+            out(JSON.stringify(envelope, null, 2) + "\n");
+        else if (parsed.dryRun)
+            out(String(envelope.diff ?? "No changes.\n"));
+        else {
+            const operation = envelope.operation;
+            out(`${envelope.command}: ${operation.idempotent_replay ? "idempotent replay" : "wrote"} ${envelope.path}\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateWriteInputError)
+            return emitInvalidInput(io, { format: detectedFormat, body: error.body });
+        if (error instanceof StateRetrievalFailure)
+            return emitRetrievalFailure(error, detectedFormat, io);
+        err(`Error: ${error.message}\n`);
+        return 1;
+    }
+}
+function fsStdin() {
+    return process.stdin.isTTY ? Buffer.alloc(0) : fs.readFileSync(0);
+}