agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/cli/dispatch/prime.js

@@ -0,0 +1,139 @@
+import { cmdPrime } from "../commands/prime.js";
+import { cmdCapability } from "../commands/capability.js";
+import { makeArgvValueReader } from "./argvParser.js";
+import { asEnvelopeFormat } from "./shared.js";
+import { emitInvalidInput } from "../errors.js";
+import { StateRetrievalFailure } from "../../state/directRetrieval.js";
+import { emitStructured } from "../structured.js";
+function emitStateFailure(error, format, io) {
+    const output = io.out ?? ((text) => process.stdout.write(text));
+    const diagnostic = io.err ?? ((text) => process.stderr.write(text));
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, output);
+    else
+        diagnostic(`Error: ${error.body.error.message}\nRecovery: ${error.body.error.recovery}\n`);
+    return error.exitCode;
+}
+export function runCapability(command, argv, io, prog) {
+    let format = "text";
+    let i = 0;
+    const value = makeArgvValueReader(argv, () => i, (n) => {
+        i = n;
+    });
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        let v = null;
+        if ((v = value("--format")) !== null) {
+            // format handled below
+        }
+        else if (a === "--fields" || a.startsWith("--fields=")) {
+            // accepted by the parser but unused by capability routing
+            if (a === "--fields")
+                i++;
+            continue;
+        }
+        else {
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
+        }
+        if (v !== null) {
+            if (v !== "text" && v !== "json" && v !== "yaml") {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')`,
+                        valid_values: ["text", "json", "yaml"],
+                    },
+                });
+            }
+            format = v;
+        }
+    }
+    try {
+        return cmdCapability(command, { format }, io);
+    }
+    catch (exc) {
+        if (exc instanceof StateRetrievalFailure)
+            return emitStateFailure(exc, format, io);
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
+}
+export function runPrime(command, argv, io, prog) {
+    const args = { command, guidance: false, context: null, dashboard: false, orientation: false, format: "text", input: null };
+    let i = 0;
+    const value = makeArgvValueReader(argv, () => i, (n) => {
+        i = n;
+    });
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        let v = null;
+        if (a === "--guidance")
+            args.guidance = true;
+        else if (a === "--dashboard")
+            args.dashboard = true;
+        else if (a === "--orientation")
+            args.orientation = true;
+        else if ((v = value("--context")) !== null)
+            args.context = v;
+        else if (a === "--input" && (!argv[i + 1] || argv[i + 1].startsWith("--"))) {
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "missing_argument", message: "--input requires a file path or -", syntax: "--input <file|->" },
+            });
+        }
+        else if ((v = value("--input")) !== null) {
+            if (v.length === 0) {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: { class: "missing_argument", message: "--input requires a file path or -", syntax: "--input <file|->" },
+                });
+            }
+            if (args.input !== null) {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: { class: "mutually_exclusive", message: "--input may only be supplied once" },
+                });
+            }
+            args.input = v;
+        }
+        else if ((v = value("--format")) !== null) {
+            if (v !== "text" && v !== "json" && v !== "yaml") {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')`,
+                        valid_values: ["text", "json", "yaml"],
+                    },
+                });
+            }
+            args.format = v;
+        }
+        else if ((v = value("--fields")) !== null) {
+            args.fields = v;
+        }
+        else {
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
+        }
+    }
+    try {
+        return cmdPrime(args, io);
+    }
+    catch (exc) {
+        if (exc instanceof StateRetrievalFailure)
+            return emitStateFailure(exc, args.format, io);
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(args.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
+}

package/dist/cli/dispatch/projections.js

@@ -0,0 +1,17 @@
+/**
+ * Independent production projections of the accepted top-level command set.
+ * They intentionally do not import the dispatcher inventory: activation must
+ * detect drift in diagnostics, packaged schema, or public instructions.
+ */
+export const DIAGNOSTIC_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);
+export const SCHEMA_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);
+export const HELP_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);

package/dist/cli/dispatch/shared.js

@@ -0,0 +1,63 @@
+export function emitDeprecationAlias(legacy, canonical, err) {
+    err(`Deprecation: agentera ${legacy} is deprecated; use agentera ${canonical}\n`);
+}
+/**
+ * Map a legacy parse-error string (the kind returned by `parse*Args`) to the
+ * canonical invalid-input envelope body. Lets the parse functions keep their
+ * simple `{ error: string }` shape while every surface's error path still
+ * funnels through `emitInvalidInput` for the frozen envelope contract.
+ */
+export function classifyParseError(raw) {
+    const required = /^the following arguments are required: (.+)$/.exec(raw);
+    if (required) {
+        return { class: "missing_argument", message: raw };
+    }
+    const unrecognized = /^unrecognized arguments: (.+)$/.exec(raw);
+    if (unrecognized) {
+        return { class: "unrecognized_argument", message: raw };
+    }
+    const choice = /^argument (--[\w-]+): invalid choice: '([^']+)' \(choose from (.+)\)$/.exec(raw);
+    if (choice) {
+        const validValues = [...choice[3].matchAll(/'([^']+)'/g)].map((m) => m[1]);
+        return {
+            class: "invalid_choice",
+            message: raw,
+            valid_values: validValues,
+        };
+    }
+    const intBad = /^argument (--[\w-]+): invalid int value: '([^']+)'$/.exec(raw);
+    if (intBad) {
+        return { class: "invalid_int", message: raw };
+    }
+    const mutex = /^argument (--[\w-]+): not allowed with argument (--[\w-]+)$/.exec(raw);
+    if (mutex) {
+        return { class: "mutually_exclusive", message: raw };
+    }
+    return { class: "unrecognized_argument", message: raw };
+}
+/** Coerce the loose `string` format field on parsed args to the literal union. */
+export function asEnvelopeFormat(format) {
+    return format === "json" || format === "yaml" ? format : "text";
+}
+/**
+ * Scan a top-level argv slice for `--format json` (or `--format=json`) so
+ * main() can decide whether to route its error envelope to stdout or stderr.
+ * Unknown format values fall through to "text" — the user will discover the
+ * mis-spelling when the underlying command runs.
+ */
+export function detectTopLevelFormat(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--format") {
+            const v = args[++i];
+            if (v === "json" || v === "text" || v === "yaml")
+                return v === "json" ? "json" : "text";
+        }
+        else if (a.startsWith("--format=")) {
+            const v = a.slice("--format=".length);
+            if (v === "json" || v === "text" || v === "yaml")
+                return v === "json" ? "json" : "text";
+        }
+    }
+    return "text";
+}

package/dist/cli/dispatch/state.js

@@ -0,0 +1,140 @@
+import { cmdQuery } from "../commands/query.js";
+import { makeArgvValueReader } from "./argvParser.js";
+import { asEnvelopeFormat, classifyParseError, detectTopLevelFormat } from "./shared.js";
+import { emitInvalidInput } from "../errors.js";
+import { runStateWrite } from "../commands/state/write.js";
+import { runStateGet } from "../commands/state/get.js";
+import { runStateList } from "../commands/state/list.js";
+import { runPlanTasks } from "../commands/state/planTasks.js";
+import { runPlans } from "../commands/state/plans.js";
+import { runExperimentRecords } from "../commands/state/experimentRecords.js";
+import { runtimeEntityFamilyForStateCommand } from "../../state/entityListRuntimeRegistry.js";
+import { entityListFamily, entityListValidValues } from "../../state/entityRetrievalHelp.js";
+import { emitStructured } from "../structured.js";
+import { verbsForArtifact } from "../../state/write/operations.js";
+function canonicalReadCorrection(familyKey, argv, io) {
+    const family = entityListFamily(familyKey);
+    const recoveryCommand = family.bareRecovery ?? family.example;
+    const format = argv.some((token, index) => token === "--format=yaml" || (token === "--format" && argv[index + 1] === "yaml"))
+        ? "yaml"
+        : detectTopLevelFormat(argv);
+    const body = {
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message: `bare state ${family.commandTokens.join(" ")} is not a canonical record-family read`,
+            syntax: `${family.syntax} | ${family.get}`,
+            valid_values: ["list", "get", ...entityListValidValues(family)],
+            example: recoveryCommand,
+            recovery: `Run \`${recoveryCommand}\`; no state was changed.`,
+            artifact: family.key,
+        },
+    };
+    if (format === "json" || format === "yaml")
+        emitStructured(body, format, io.out ?? ((text) => process.stdout.write(text)));
+    else
+        (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${body.error.message}\nSyntax: ${body.error.syntax}\nExample: ${body.error.example}\nRecovery: ${body.error.recovery}\n`);
+    return 2;
+}
+export function runState(command, argv, io, prog) {
+    const runtime = runtimeEntityFamilyForStateCommand(command, argv);
+    if (runtime) {
+        const offset = runtime.commandTokens.length - 1;
+        const familyArgv = argv.slice(offset);
+        const verb = familyArgv[0];
+        if (verb === "list" || verb === "get") {
+            if (runtime.parser === "generic")
+                return verb === "list" ? runStateList(command, familyArgv.slice(1), io) : runStateGet(command, familyArgv.slice(1), io);
+            if (runtime.parser === "plans")
+                return runPlans(familyArgv, io);
+            if (runtime.parser === "plan_tasks")
+                return runPlanTasks(familyArgv, io);
+            return runExperimentRecords(familyArgv, io);
+        }
+        const family = entityListFamily(runtime.key);
+        const writeVerb = verb !== undefined && verbsForArtifact(command).some((candidate) => candidate === verb);
+        if (writeVerb && runtime.commandTokens.length === 1)
+            return runStateWrite(command, argv, io);
+        if (family.bareRead === "alias")
+            return runStateList(command, familyArgv, io);
+        return canonicalReadCorrection(family.key, familyArgv, io);
+    }
+    if (argv[0] && verbsForArtifact(command).some((candidate) => candidate === argv[0])) {
+        return runStateWrite(command, argv, io);
+    }
+    return emitInvalidInput(io, {
+        format: detectTopLevelFormat(argv),
+        body: { class: "unsupported_target", message: `unsupported state artifact or operation '${command} ${argv[0] ?? ""}'`.trim() },
+    });
+}
+export function parseQueryArgs(argv) {
+    const args = {
+        query: null,
+        list_artifacts: false,
+        topic: null,
+        severity: null,
+        dimension: null,
+        status: null,
+        limit: null,
+        format: "text",
+        fields: null,
+    };
+    let i = 0;
+    const value = makeArgvValueReader(argv, () => i, (n) => {
+        i = n;
+    });
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        let v;
+        if (a === "--list-artifacts")
+            args.list_artifacts = true;
+        else if ((v = value("--topic")) !== null)
+            args.topic = v;
+        else if ((v = value("--severity")) !== null)
+            args.severity = v;
+        else if ((v = value("--dimension")) !== null)
+            args.dimension = v;
+        else if ((v = value("--status")) !== null)
+            args.status = v;
+        else if ((v = value("--limit")) !== null) {
+            const n = Number(v);
+            if (!Number.isInteger(n))
+                return { error: `argument --limit: invalid int value: '${v}'` };
+            args.limit = n;
+        }
+        else if ((v = value("--format")) !== null) {
+            if (v !== "text" && v !== "json" && v !== "yaml") {
+                return { error: `argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')` };
+            }
+            args.format = v;
+        }
+        else if ((v = value("--fields")) !== null)
+            args.fields = v;
+        else if (a.startsWith("--"))
+            return { error: `unrecognized arguments: ${a}` };
+        else if (args.query === null)
+            args.query = a;
+        else
+            return { error: `unrecognized arguments: ${a}` };
+    }
+    return args;
+}
+export function runQuery(argv, io, prog) {
+    const parsed = parseQueryArgs(argv);
+    if ("error" in parsed) {
+        return emitInvalidInput(io, {
+            format: detectTopLevelFormat(argv),
+            body: classifyParseError(parsed.error),
+        });
+    }
+    try {
+        return cmdQuery(parsed, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(parsed.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
+}