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

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

@@ -1,172 +1,14 @@
-/**
- * `state plan` query (active PLAN.yaml → summary + task list).
- *
- * Source-contract builder for plan artifacts: declares the
- * `complete_for_plan_artifact` / `complete_for_normal_startup_evaluation`
- * flags that downstream capabilities (prime, hej, orkestrera) read
- * before raw plan access.
- */
-import { asList, emitStateStructured, filterByFieldValue, formatEntry, loadArtifact, missingSchemaError, printStatusCounts, sourceMetadata, statusCounts, structuredState, truncate, } from "../../stateQuery.js";
-import { artifactPath } from "../../appContext.js";
-import { firstPresent } from "../../stateQuery.js";
-import { out, err } from "./shared.js";
-function planArtifactSummary(data, header) {
-    const summary = {
-        header,
-        title: firstPresent(header, ["title"], data.title ?? ""),
-        status: firstPresent(header, ["status"], data.status ?? ""),
-        created: firstPresent(header, ["created"], data.created ?? ""),
-        what: data.what,
-        why: data.why,
-        constraints: data.constraints,
-        scope: data.scope,
-        design: data.design,
-        overall_acceptance: data.overall_acceptance,
-        surprises: data.surprises,
-        previous_plan_archived: data.previous_plan_archived,
-    };
-    const out = {};
-    for (const [k, v] of Object.entries(summary)) {
-        if (v !== null && v !== undefined && v !== "")
-            out[k] = v;
-    }
-    return out;
-}
-function planSourceContract(source, summary) {
-    const legacyEntries = Boolean(summary.legacy_entries);
-    const complete = Boolean(source.exists) && !legacyEntries;
-    const missingState = [];
-    if (!source.exists)
-        missingState.push("plan artifact");
-    if (legacyEntries)
-        missingState.push("current plan task artifact shape");
-    const summaryFields = Object.keys(summary).sort();
-    const entryFields = ["number", "name", "depends_on", "status", "acceptance", "evidence", "blocked_reason"];
-    return {
-        artifact: "plan",
-        canonical_artifact_label: "plan",
-        persisted_artifact_path: source.path,
-        complete_for_plan_artifact: complete,
-        complete_for_normal_startup_evaluation: complete,
-        raw_artifact_reads_required: false,
-        raw_artifact_read_policy: "Use `agentera state plan --format json` entries, summary, source, and source_contract before raw plan access. " +
-            "When complete_for_plan_artifact is true, skip defensive `.agentera/plan.yaml` reads during normal read-only " +
-            "plan startup/evaluation; raw plan artifact access is reserved for writes, archival, validation, corruption " +
-            "diagnostics, or unavailable/incomplete CLI state.",
-        included_state: [
-            "header",
-            "what",
-            "why",
-            "constraints",
-            "scope",
-            "design",
-            "tasks",
-            "task dependencies",
-            "task acceptance criteria",
-            "task evidence",
-            "overall_acceptance",
-            "surprises",
-            "previous_plan_archived",
-        ],
-        complete_state: {
-            summary: summaryFields,
-            entries: entryFields,
-            normal_startup_evaluation: complete,
-        },
-        raw_artifact_access_boundary: {
-            normal_read_only_startup_evaluation: "skip raw plan artifact reads when complete_for_plan_artifact is true",
-            allowed_raw_artifact_uses: [
-                "artifact writes",
-                "plan archival",
-                "artifact validation",
-                "corruption diagnostics",
-                "unavailable or incomplete CLI state after CLI fallbacks",
-            ],
-        },
-        missing_state: missingState,
-        fallback: complete ? [] : ["agentera docs --format json"],
-        fallback_policy: "When plan CLI output is missing or incomplete, use supported CLI state such as `agentera docs --format json` " +
-            "for artifact mapping before any last-resort raw plan artifact read.",
-        summary_fields: summaryFields,
-        entry_fields: entryFields,
-    };
-}
-export function queryPlan(args, schemas, io) {
-    const o = out(io);
-    const e = err(io);
-    const info = schemas.plan;
-    if (!info) {
-        e(missingSchemaError("plan") + "\n");
-        return 1;
-    }
-    const p = artifactPath(info, "plan");
-    const data = loadArtifact(p);
-    const isDict = data !== null && typeof data === "object" && !Array.isArray(data);
+import { emitStructured } from "../../structured.js";
+import { currentPlanEntityView } from "../../../state/planEntities.js";
+import YAML from "yaml";
+import { out } from "./shared.js";
+export function queryPlan(args, _schemas, io) {
     const format = args.format ?? "text";
-    if (!isDict) {
-        if (format !== "text") {
-            const source = sourceMetadata("plan", p);
-            const summary = { absence_reason: "No plan artifact is available from agentera plan." };
-            return emitStateStructured("plan", structuredState("plan", [], source, {
-                filters: { status: args.status ?? null },
-                summary,
-                sourceContract: planSourceContract(source, summary),
-            }), format, args.fields, o, e);
-        }
-        return 0;
-    }
-    const dataDict = data;
-    const legacyEntries = asList(dataDict.entries);
-    if (legacyEntries.length > 0) {
-        let entries = legacyEntries;
-        const statusFilter = args.status ?? null;
-        if (statusFilter)
-            entries = filterByFieldValue(entries, "status", statusFilter);
-        const source = sourceMetadata("plan", p);
-        const summary = { legacy_entries: true };
-        if (format !== "text") {
-            return emitStateStructured("plan", structuredState("plan", entries, source, {
-                filters: { status: statusFilter },
-                summary,
-                sourceContract: planSourceContract(source, summary),
-            }), format, args.fields, o, e);
-        }
-        for (const entry of entries) {
-            const line = formatEntry(entry, ["status", "title", "name"]);
-            if (line)
-                o(line + "\n");
-        }
-        return 0;
-    }
-    const header = dataDict.header && typeof dataDict.header === "object" && !Array.isArray(dataDict.header) ? dataDict.header : {};
-    const summary = planArtifactSummary(dataDict, header);
-    const title = summary.title ?? "";
-    const status = summary.status ?? "";
-    const created = summary.created ?? "";
-    let tasks = asList(dataDict.tasks);
-    const statusFilter = args.status ?? null;
-    if (statusFilter)
-        tasks = filterByFieldValue(tasks, "status", statusFilter);
-    const source = sourceMetadata("plan", p);
-    if (format !== "text") {
-        return emitStateStructured("plan", structuredState("plan", tasks, source, {
-            filters: { status: statusFilter },
-            summary,
-            sourceContract: planSourceContract(source, summary),
-        }), format, args.fields, o, e);
-    }
-    o(`Plan: status=${status || "unknown"} | title=${truncate(title)} | created=${created || "-"}\n`);
-    for (const key of ["what", "why"]) {
-        const value = dataDict[key];
-        if (value)
-            o(`${key}: ${truncate(value)}\n`);
-    }
-    printStatusCounts("Task status", statusCounts(tasks), o);
-    for (const task of tasks.slice(0, 10)) {
-        const line = formatEntry(task, ["number", "status", "name", "title"]);
-        if (line)
-            o(`Task: ${line}\n`);
-    }
+    const response = currentPlanEntityView(process.cwd(), args.limit ?? undefined, args.cursor ?? undefined, args.status ?? undefined, { format });
+    const output = out(io);
+    if (format === "text")
+        output(YAML.stringify(response));
+    else
+        emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=plan.js.map

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

@@ -0,0 +1,154 @@
+import YAML from "yaml";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { getPlanTaskEntity, listPlanTaskEntities } from "../../../state/planEntities.js";
+import { emitStructured } from "../../structured.js";
+import { entityListFamily, entityListValidValues } from "../../../state/entityRetrievalHelp.js";
+function requestedFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const value = token === "--format" ? argv[index + 1] : token.startsWith("--format=") ? token.slice(9) : undefined;
+        if (value === "json" || value === "yaml")
+            return value;
+    }
+    return "text";
+}
+function readValue(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value, next: index + 2 };
+}
+function failure(message, verb) {
+    const list = verb === "list";
+    const family = entityListFamily("plan_tasks");
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message,
+            syntax: list
+                ? family.syntax
+                : family.get,
+            example: list
+                ? family.example
+                : "agentera state plan tasks get --id qjtrmnpvka --format json",
+            recovery: list ? `Run \`${family.example}\`; no state was changed.` : "Correct the command using one of the valid forms and retry; no state was changed.",
+            valid_values: list
+                ? entityListValidValues(family)
+                : ["get", "--id ID", "--format text|json|yaml"],
+        },
+    }, 2);
+}
+function parse(argv, verb) {
+    const family = entityListFamily("plan_tasks");
+    let format = "text";
+    let plan;
+    let limit = family.bounds.default;
+    let cursor;
+    let id;
+    const selector = {};
+    const seen = new Set();
+    for (let index = 0; index < argv.length;) {
+        const token = argv[index];
+        if (verb === "list" && token === "--ids-only") {
+            if (selector.idsOnly)
+                throw failure("--ids-only may only be supplied once", verb);
+            selector.idsOnly = true;
+            index += 1;
+            continue;
+        }
+        if (verb === "list" && !token.startsWith("--")) {
+            if (plan)
+                throw failure(`unrecognized argument '${token}'`, verb);
+            plan = token;
+            index += 1;
+            continue;
+        }
+        const allowed = verb === "list" ? ["--format", "--limit", "--cursor", "--fields"] : ["--format", "--id"];
+        const name = allowed.find((flag) => token === flag || token.startsWith(`${flag}=`));
+        if (!name)
+            throw failure(`unrecognized argument '${token}'`, verb);
+        if (seen.has(name))
+            throw failure(`${name} may only be supplied once`, verb);
+        seen.add(name);
+        let parsed;
+        try {
+            parsed = readValue(argv, index, name);
+        }
+        catch (error) {
+            throw failure(error.message, verb);
+        }
+        index = parsed.next;
+        if (name === "--format") {
+            if (!family.formats.includes(parsed.value))
+                throw failure(`invalid --format '${parsed.value}'`, verb);
+            format = parsed.value;
+        }
+        else if (name === "--limit") {
+            if (!/^[1-9][0-9]*$/.test(parsed.value) || Number(parsed.value) < family.bounds.minimum || Number(parsed.value) > family.bounds.maximum)
+                throw failure(`--limit must be an integer from ${family.bounds.minimum} through ${family.bounds.maximum}`, verb);
+            limit = Number(parsed.value);
+        }
+        else if (name === "--cursor")
+            cursor = parsed.value;
+        else if (name === "--fields")
+            selector.fields = parsed.value;
+        else
+            id = parsed.value;
+    }
+    if (verb === "get" && !id)
+        throw failure("entity mode requires a bare ten-letter --id selector", verb);
+    return { format, limit, ...(plan ? { plan } : {}), ...(cursor ? { cursor } : {}), ...(id ? { id } : {}), selector };
+}
+function emitFailure(error, format, io) {
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, io.out ?? ((text) => process.stdout.write(text)));
+    else {
+        const detail = error.body.error;
+        (io.err ?? ((text) => process.stderr.write(text)))([
+            `Error: ${detail.message}`,
+            `Class: ${detail.class}`,
+            `Valid forms: ${(detail.valid_values ?? [detail.syntax]).join("; ")}`,
+            `Example: ${detail.example}`,
+            `Recovery: ${detail.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+export function runPlanTasks(argv, io) {
+    const format = requestedFormat(argv);
+    const verb = argv[0];
+    if (verb !== "list" && verb !== "get")
+        return emitFailure(failure(`expected 'list' or 'get', received '${verb ?? "nothing"}'`, "list"), format, io);
+    try {
+        const args = parse(argv.slice(1), verb);
+        const response = verb === "list"
+            ? listPlanTaskEntities(process.cwd(), args.plan, args.limit, args.cursor, { format: args.format, selector: args.selector })
+            : getPlanTaskEntity(process.cwd(), args.id);
+        const output = io.out ?? ((text) => process.stdout.write(text));
+        if (args.format === "json" || args.format === "yaml")
+            emitStructured(response, args.format, output);
+        else
+            output(YAML.stringify(response));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            return emitFailure(error, format, io);
+        return emitFailure(new StateRetrievalFailure({
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "unsupported_state",
+                message: error.message,
+                syntax: "agentera state plan tasks {list|get} [options]",
+                example: "agentera state plan tasks list --format json",
+                recovery: "Use a supported active plan and retry; no state was changed.",
+            },
+        }, 1), format, io);
+    }
+}

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

@@ -0,0 +1,154 @@
+import YAML from "yaml";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { getPlanEntity, listPlanEntities } from "../../../state/planEntities.js";
+import { emitStructured } from "../../structured.js";
+import { entityListFamily, entityListValidValues } from "../../../state/entityRetrievalHelp.js";
+function requestedFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const value = token === "--format" ? argv[index + 1] : token.startsWith("--format=") ? token.slice(9) : undefined;
+        if (value === "json" || value === "yaml")
+            return value;
+    }
+    return "text";
+}
+function failure(message, verb) {
+    const list = verb === "list";
+    const family = entityListFamily("plans");
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message,
+            syntax: list
+                ? family.syntax
+                : family.get,
+            example: list
+                ? family.example
+                : "agentera state plan get --id qjtrmnpvka --format json",
+            recovery: list ? `Run \`${family.example}\`; no state was changed.` : "Correct the command using one of the valid forms and retry; no state was changed.",
+            valid_values: list
+                ? entityListValidValues(family)
+                : ["get", "--id ID", "--format text|json|yaml"],
+        },
+    }, 2);
+}
+function readValue(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value, next: index + 2 };
+}
+function parse(argv, verb) {
+    const family = entityListFamily("plans");
+    let format = "text";
+    let limit = family.bounds.default;
+    let cursor;
+    let id;
+    let status;
+    const selector = {};
+    const seen = new Set();
+    for (let index = 0; index < argv.length;) {
+        const token = argv[index];
+        if (verb === "list" && token === "--ids-only") {
+            if (selector.idsOnly)
+                throw failure("--ids-only may only be supplied once", verb);
+            selector.idsOnly = true;
+            index += 1;
+            continue;
+        }
+        const allowed = verb === "list" ? ["--format", "--limit", "--cursor", "--status", "--fields"] : ["--format", "--id"];
+        const name = allowed.find((flag) => token === flag || token.startsWith(`${flag}=`));
+        if (!name) {
+            throw failure(`unrecognized argument '${token}'`, verb);
+        }
+        if (seen.has(name))
+            throw failure(`${name} may only be supplied once`, verb);
+        seen.add(name);
+        let parsed;
+        try {
+            parsed = readValue(argv, index, name);
+        }
+        catch (error) {
+            throw failure(error.message, verb);
+        }
+        index = parsed.next;
+        if (name === "--format") {
+            if (!family.formats.includes(parsed.value))
+                throw failure(`invalid --format '${parsed.value}'`, verb);
+            format = parsed.value;
+        }
+        else if (name === "--limit") {
+            if (!/^[1-9][0-9]*$/.test(parsed.value) || Number(parsed.value) < family.bounds.minimum || Number(parsed.value) > family.bounds.maximum)
+                throw failure(`--limit must be an integer from ${family.bounds.minimum} through ${family.bounds.maximum}`, verb);
+            limit = Number(parsed.value);
+        }
+        else if (name === "--cursor")
+            cursor = parsed.value;
+        else if (name === "--fields")
+            selector.fields = parsed.value;
+        else if (name === "--status") {
+            const validStatuses = family.filters.find(({ name }) => name === "status")?.values;
+            if (!Array.isArray(validStatuses) || !validStatuses.includes(parsed.value))
+                throw failure(`invalid --status '${parsed.value}'`, verb);
+            status = parsed.value;
+        }
+        else
+            id = parsed.value;
+    }
+    return { format, limit, ...(cursor ? { cursor } : {}), ...(id ? { id } : {}), ...(status ? { status } : {}), selector };
+}
+function emitFailure(error, format, io) {
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, io.out ?? ((text) => process.stdout.write(text)));
+    else {
+        const detail = error.body.error;
+        (io.err ?? ((text) => process.stderr.write(text)))([
+            `Error: ${detail.message}`,
+            `Class: ${detail.class}`,
+            `Valid forms: ${(detail.valid_values ?? [detail.syntax]).join("; ")}`,
+            `Example: ${detail.example}`,
+            `Recovery: ${detail.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+export function runPlans(argv, io) {
+    const format = requestedFormat(argv);
+    const verb = argv[0];
+    if (verb !== "list" && verb !== "get")
+        return emitFailure(failure(`expected 'list' or 'get', received '${verb ?? "nothing"}'`, "list"), format, io);
+    try {
+        const args = parse(argv.slice(1), verb);
+        if (verb === "get" && !args.id)
+            throw failure("entity mode requires --id ID", verb);
+        const response = verb === "list"
+            ? listPlanEntities(process.cwd(), args.limit, args.cursor, { format: args.format, selector: args.selector, ...(args.status ? { statuses: [args.status] } : {}) })
+            : getPlanEntity(process.cwd(), args.id);
+        const output = io.out ?? ((text) => process.stdout.write(text));
+        if (args.format === "json" || args.format === "yaml")
+            emitStructured(response, args.format, output);
+        else
+            output(YAML.stringify(response));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            return emitFailure(error, format, io);
+        return emitFailure(new StateRetrievalFailure({
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "unsupported_state",
+                message: error.message,
+                syntax: "agentera state plan {list|get} [options]",
+                example: "agentera state plan list --format json",
+                recovery: "Use supported plan state and retry; no state was changed.",
+            },
+        }, 1), format, io);
+    }
+}

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

@@ -1,47 +1,13 @@
-/**
- * `state progress` query (PROGRESS.md / progress.yaml cycles).
- *
- * Reports the most recent N cycles (default 5), filtered by topic or
- * type, with a structured envelope that downstream prime/hej callers
- * use to surface progress_verification without raw artifact reads.
- */
-import { emitStateStructured, extractEntries, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, progressEntriesForOutput, recentCycles, sourceMetadata, structuredState, truncate, } from "../../stateQuery.js";
-import { artifactPath } from "../../appContext.js";
-import { out, err } from "./shared.js";
-export function queryProgress(args, schemas, io) {
-    const o = out(io);
-    const e = err(io);
-    const info = schemas.progress;
-    if (!info) {
-        e(missingSchemaError("progress") + "\n");
-        return 1;
-    }
-    const p = artifactPath(info, "progress");
-    const data = loadArtifact(p);
-    let entries = extractEntries(data);
-    const topic = args.topic ?? null;
-    if (topic)
-        entries = filterByTopic(entries, topic, info.fields);
-    const statusFilter = args.status ?? null;
-    if (statusFilter)
-        entries = filterByFieldValue(entries, "type", statusFilter);
-    const effectiveLimit = (args.limit ?? 5) || 5;
-    entries = recentCycles(entries, effectiveLimit);
-    if ((args.format ?? "text") !== "text") {
-        return emitStateStructured("progress", structuredState("progress", progressEntriesForOutput(entries), sourceMetadata("progress", p), {
-            filters: { topic, status: statusFilter, limit: effectiveLimit },
-        }), args.format ?? "text", args.fields, o, e);
-    }
-    if (entries.length === 0)
-        return 0;
-    for (const entry of entries) {
-        o(formatEntry(entry, ["number", "timestamp", "type", "phase"]) + "\n");
-        for (const key of ["what", "verified", "next"]) {
-            const value = entry[key];
-            if (value)
-                o(`  ${key}: ${truncate(value)}\n`);
-        }
-    }
+import { emitStructured } from "../../structured.js";
+import { listProgressEntities, renderProgressEntityListText } from "../../../state/progressEntities.js";
+import { out } from "./shared.js";
+export function queryProgress(args, _schemas, io) {
+    const format = (args.format ?? "text");
+    const response = listProgressEntities(process.cwd(), args.limit ?? undefined, { topic: args.topic, status: args.status }, args.cursor ?? undefined, { format });
+    const output = out(io);
+    if (format === "text")
+        output(renderProgressEntityListText(response));
+    else
+        emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=progress.js.map

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

@@ -12,4 +12,3 @@ export function out(io) {
 export function err(io) {
     return io.err ?? ((t) => process.stderr.write(t));
 }
-//# sourceMappingURL=shared.js.map