agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/cli/commands/schema.js

@@ -1,52 +1,135 @@
 import fs from "node:fs";
 import path from "node:path";
-import { parseYaml } from "../../core/yaml.js";
-import { activeAppModel, discoverSchemasDir, loadSchemas, } from "../appContext.js";
+import { activeAppModel, discoverSchemasDir, loadSchemas } from "../appContext.js";
 import { emitStructured } from "../structured.js";
-import { appModelPayload, REQUIRED_SPARSE_CONTEXT_FIELDS, ROUTINE_STRUCTURED_FIELDS, surfaceMissingMessage, } from "../stateQuery.js";
+import { appModelPayload, REQUIRED_SPARSE_CONTEXT_FIELDS, ROUTINE_STRUCTURED_FIELDS, PRIME_STRUCTURED_FIELDS, surfaceMissingMessage, } from "../stateQuery.js";
 import { artifactLocationContract } from "./query.js";
+import { stateWriterArtifactContract, stateWriterContract } from "../../state/write/operations.js";
+import { CANONICAL_SHARED_SKILL_PATH } from "../../setup/sharedSkill.js";
+import { loadStateRetrievalAuthority } from "../../state/retrievalAuthority.js";
+import { entityListFamilies } from "../../state/entityRetrievalHelp.js";
+import { personalGlossaryOutputContract } from "../../registries/glossaryEntryContract.js";
+import { describeArtifactSchemaFields } from "../../registries/artifactSchemaProjection.js";
+import { advertisedValidateFamilyNames } from "./validate.js";
+import { SCHEMA_TOP_LEVEL_COMMANDS } from "../dispatch/projections.js";
+export const TRANSITIONAL_TOP_LEVEL_ALIASES = [
+    {
+        legacy: "query",
+        canonical: "state query",
+        structuredExampleArgv: ["query", "--list-artifacts", "--format", "json"],
+    },
+    {
+        legacy: "compact",
+        canonical: "check compact",
+        structuredExampleArgv: ["compact", "--project", "PROJECT", "--format", "json"],
+    },
+    {
+        legacy: "verify",
+        canonical: "check verify",
+        structuredExampleArgv: ["verify", "eval", "skills", "--dry-run", "--format", "json"],
+    },
+    {
+        legacy: "stats",
+        canonical: "report",
+        structuredExampleArgv: ["stats", "refresh", "--dry-run", "--format", "json"],
+    },
+    {
+        legacy: "lint",
+        canonical: "check lint",
+        structuredExampleArgv: [
+            "lint", "--artifact", "progress", "--text", "alias-parity", "--format", "json",
+        ],
+    },
+    {
+        legacy: "validate",
+        canonical: "check validate",
+        structuredExampleArgv: ["validate", "capability-contract", "--format", "json"],
+    },
+];
+export const REMOVED_TOP_LEVEL_CORRECTIONS = {
+    status: "prime",
+    hej: "prime",
+    describe: "schema",
+    gate: "check compact",
+    progress: "state progress",
+    health: "state health",
+    todo: "state todo",
+    decisions: "state decisions",
+    docs: "state docs",
+    objective: "state objective",
+    experiments: "state experiments",
+};
+function projectedStateRetrieval(retrieval) {
+    const projected = JSON.parse(JSON.stringify(retrieval));
+    const commands = projected.commands;
+    const families = (projected.list_help.families);
+    for (const family of entityListFamilies()) {
+        commands[family.key] = { list: family.syntax, get: family.get };
+        const source = families[family.key];
+        source.example = family.example;
+        if (family.bareRecovery)
+            source.bare_recovery = family.bareRecovery;
+    }
+    return projected;
+}
 const CAPABILITY_NAMES = [
-    "status", "vision", "discuss", "research", "plan", "build",
-    "optimize", "audit", "document", "profile", "design", "orchestrate",
+    "status",
+    "vision",
+    "discuss",
+    "research",
+    "plan",
+    "build",
+    "optimize",
+    "audit",
+    "document",
+    "profile",
+    "design",
+    "orchestrate",
 ];
 const ROUTINE_STATE_COMMANDS = [
-    "status", "plan", "progress", "health", "todo", "decisions", "docs", "objective", "experiments",
+    "status",
+    "plan",
+    "progress",
+    "health",
+    "todo",
+    "decisions",
+    "docs",
+    "objective",
+    "experiments",
 ];
 const DOCTOR_SIGNAL_KINDS = [
-    "missing_bundle", "invalid_install_root", "unmanaged_install_root", "invalid_bundle",
-    "missing_marker", "version_mismatch",
+    "missing_bundle",
+    "invalid_install_root",
+    "unmanaged_install_root",
+    "invalid_bundle",
+    "missing_marker",
+    "version_mismatch",
+    "corrupt_bundle_marker",
+];
+const DOCTOR_SELF_CHECK_CATEGORIES = [
+    "Agentera CLI self-check status",
+    "installed app and install-root status",
+    "canonical shared-skill diagnosis",
+    "project integration and project-state migration diagnostics",
+    "bounded offline smoke checks when requested",
 ];
-const STATUS_STRUCTURED_FIELDS = [
-    "command", "status", "app_home", "app", "mode", "profile", "v1_migration", "health",
-    "todo", "plan", "docs", "progress", "objective", "state_presence", "attention",
-    "decision_attention", "next_action", "orchestration_context", "closeout_context",
-    "evidence_context", "benchmark_context", "execution_context", "source", "source_contract",
+const DOCTOR_EXCLUDES = [
+    "project artifact health",
+    "codebase quality audit findings",
+    "capability architecture, test, dependency, or documentation audit output",
 ];
+const STATUS_STRUCTURED_FIELDS = PRIME_STRUCTURED_FIELDS;
 const COMMAND_DESCRIPTIONS = {
-    prime: "Composite orientation briefing and capability startup context.",
-    status: "Deprecated alias for prime.",
+    prime: "Composite orientation briefing and capability startup context; bare JSON is at most 12000 UTF-8 bytes and status startup at most 22500.",
     schema: "Runtime CLI/schema introspection.",
-    plan: "Deprecated alias for state plan. Active plan summary.",
-    progress: "Deprecated alias for state progress. Recent cycle summary.",
-    health: "Deprecated alias for state health. Latest project artifact health audit.",
-    todo: "Deprecated alias for state todo. TODO summary.",
-    decisions: "Deprecated alias for state decisions. Decision log.",
-    docs: "Deprecated alias for state docs. Documentation contract summary.",
-    objective: "Deprecated alias for state objective. Active optimize objective summary.",
-    experiments: "Deprecated alias for state experiments. Active optimize experiments summary.",
     query: "Deprecated alias for state query. Advanced custom artifact query.",
-    lint: "Deprecated alias for check lint. Run pre-write artifact prose self-audit.",
-    gate: "Deprecated alias for check compact. Run check-only repository gates.",
+    lint: "Deprecated alias for check lint. Optional draft prose preview; typed writers validate published bytes.",
     compact: "Deprecated alias for check compact. Check or fix artifact compaction budgets.",
-    upgrade: "Preview or apply phased upgrade with semver and channel gate; v2→v3 migrates to latest on selected channel (irreversible).",
-    doctor: "Check Agentera CLI, app, and runtime status.",
-    describe: "Deprecated alias for schema.",
-};
-const COMMAND_FILTERS_SCHEMA = {
-    prime: [],
-    status: [],
-    schema: ["format"],
-    describe: ["format"],
+    verify: "Deprecated alias for check verify. Run bounded verification families.",
+    stats: "Deprecated alias for report. Read or refresh privacy-gated usage analytics.",
+    validate: "Deprecated alias for check validate. Validate capabilities and repository contracts.",
+    upgrade: "Preview or apply one-way app and project-state migration.",
+    doctor: "Check Agentera CLI, app, shared-skill, and project-integration status.",
 };
 function availableStructuredFields(command) {
     if (command === "prime")
@@ -70,87 +153,55 @@ const COMMAND_FILTERS_ALL = {
     experiments: ["topic", "status", "limit"],
     query: ["list_artifacts", "topic", "severity", "dimension", "status", "limit"],
     lint: ["artifact", "file", "text", "strict", "format"],
-    gate: ["project", "format"],
     compact: ["project", "mode", "format"],
     doctor: ["install_root", "home", "project", "expected_version", "expect_command"],
-    upgrade: ["project", "install_root", "home", "runtime", "only", "dry_run", "yes", "force", "update_packages", "channel"],
-    describe: ["format"],
+    upgrade: [
+        "project",
+        "install_root",
+        "home",
+        "only",
+        "dry_run",
+        "yes",
+        "force",
+        "channel",
+    ],
     schema: ["format"],
 };
-function contractPath() {
+function integrationAuthorityPath() {
     const sourceRoot = path.resolve(discoverSchemasDir(), "..", "..", "..", "..");
-    return path.join(sourceRoot, "references", "cli", "agent-ready-state-contract.yaml");
-}
-function loadDecision45Contract() {
-    const p = contractPath();
-    let isFile = false;
-    try {
-        isFile = fs.statSync(p).isFile();
-    }
-    catch {
-        isFile = false;
-    }
-    if (!isFile)
-        return [null, "Decision 45 CLI contract is missing"];
-    try {
-        // cast: parseYaml result of the Decision 45 contract file (YAML IO boundary)
-        return [parseYaml(fs.readFileSync(p, "utf8")), null];
-    }
-    catch (exc) {
-        return [null, `Decision 45 CLI contract could not be read: ${exc.message}`];
-    }
-}
-function schemaFieldDescription(entry) {
-    return {
-        id: entry.id ?? null,
-        field: entry.field ?? null,
-        type: entry.type ?? "unknown",
-        required: "required" in entry ? entry.required : "unknown",
-        format: entry.format ?? null,
-        validation: entry.validation ?? [],
-    };
+    return path.join(sourceRoot, "skills", "agentera", "SKILL.md");
 }
-const FIELD_SKIP = new Set([
-    "meta", "GROUP_PREFIXES", "BUDGET", "COMPACTION", "VALIDATION", "ARCHIVE", "CONVENTION", "CONVENTIONS",
-]);
-function describeSchemaFields(schema) {
-    const fields = [];
-    for (const [groupKey, groupVal] of Object.entries(schema)) {
-        if (FIELD_SKIP.has(groupKey) || !groupVal || typeof groupVal !== "object" || Array.isArray(groupVal))
-            continue;
-        // cast: groupVal is a parsed artifact schema field group (YAML IO boundary)
-        for (const entry of Object.values(groupVal)) {
-            if (entry && typeof entry === "object" && !Array.isArray(entry) && "field" in entry) {
-                // cast: entry is a parsed field descriptor from the schema (YAML IO boundary)
-                const field = schemaFieldDescription(entry);
-                field.group = groupKey;
-                fields.push(field);
-            }
-        }
-    }
-    return fields;
-}
-function commandDescription(name, kind, fields = null) {
-    let outputFormats = ["text", "json", "yaml"];
-    if (name === "lint")
-        outputFormats = ["text", "json"];
-    else if (name === "compact" || name === "gate")
-        outputFormats = ["text", "json"];
-    else if (name === "doctor")
-        outputFormats = ["text", "json"];
-    else if (name === "upgrade")
-        outputFormats = ["text", "json"];
-    else if (name === "describe" || name === "schema")
-        outputFormats = ["json", "yaml"];
-    else if (name === "prime")
-        outputFormats = ["text", "json", "yaml"];
+function commandDescription(name, kind, fields = null, outputFormats, filters) {
+    let formats = outputFormats ?? ["text", "json", "yaml"];
+    if (!outputFormats && name === "lint")
+        formats = ["text", "json"];
+    else if (!outputFormats && name === "compact")
+        formats = ["text", "json"];
+    else if (!outputFormats && name === "doctor")
+        formats = ["text", "json"];
+    else if (!outputFormats && name === "upgrade")
+        formats = ["text", "json"];
+    else if (!outputFormats && name === "schema")
+        formats = ["json", "yaml"];
+    else if (!outputFormats && name === "prime")
+        formats = ["text", "json", "yaml"];
+    const description = kind === "capability_routing"
+        ? `Route to ${name} capability guidance.`
+        : kind === "routine_state"
+            ? `Read ${name} project state through the agentera state namespace.`
+            : COMMAND_DESCRIPTIONS[name] ?? "unknown";
+    const alias = TRANSITIONAL_TOP_LEVEL_ALIASES.find((entry) => entry.legacy === name);
     return {
         name,
         kind,
-        description: COMMAND_DESCRIPTIONS[name] ?? "unknown",
-        filters: COMMAND_FILTERS_ALL[name] ?? [],
-        output_formats: outputFormats,
+        description,
+        filters: filters ?? COMMAND_FILTERS_ALL[name] ?? [],
+        output_formats: formats,
         structured_fields: fields ?? [],
+        ...(alias ? {
+            alias_for: alias.canonical,
+            structured_example_argv: alias.structuredExampleArgv,
+        } : {}),
     };
 }
 function describeCommands() {
@@ -165,16 +216,40 @@ function describeCommands() {
     for (const name of ROUTINE_STATE_COMMANDS) {
         commands.push(commandDescription(name, "routine_state", availableStructuredFields(name)));
     }
-    commands.push(commandDescription("query", "advanced_artifact_query"), commandDescription("lint", "artifact_lint", ["command", "status", "artifact", "checks", "summary"]), commandDescription("compact", "artifact_compaction", ["command", "status", "project", "summary", "operations"]), commandDescription("schema", "runtime_introspection"), commandDescription("upgrade", "upgrade"), commandDescription("doctor", "self_check"));
+    commands.push(commandDescription("query", "advanced_artifact_query"), commandDescription("compact", "artifact_compaction", [
+        "command",
+        "status",
+        "project",
+        "summary",
+        "operations",
+    ]), commandDescription("verify", "verification", [
+        "command",
+        "status",
+        "family",
+        "target",
+        "engine",
+        "diagnostics",
+        "safety",
+    ]), commandDescription("stats", "usage_analytics"), commandDescription("lint", "artifact_lint", [
+        "command",
+        "status",
+        "artifact",
+        "checks",
+        "summary",
+    ]), commandDescription("validate", "validation"), commandDescription("schema", "runtime_introspection"), commandDescription("upgrade", "upgrade", [
+        "schemaVersion",
+        "mode",
+        "status",
+        "phase",
+        "phases",
+        "summary",
+        "state_validation",
+        "startup_validation",
+        "dryRunCommand",
+        "applyCommand",
+    ]), commandDescription("doctor", "self_check"));
     return commands;
 }
-function contractSection(contract, key, gaps) {
-    if (contract && typeof contract === "object" && !Array.isArray(contract) && key in contract) {
-        return contract[key];
-    }
-    gaps.push({ scope: key, status: "unknown", message: `Decision 45 contract section '${key}' is unavailable` });
-    return null;
-}
 function describeArtifactSchemas(schemasDir, schemas, model, artifactLocations) {
     const gaps = [];
     let isDir = false;
@@ -199,8 +274,9 @@ function describeArtifactSchemas(schemasDir, schemas, model, artifactLocations)
         // cast: schema.meta is read from a parsed artifact schema (YAML IO boundary)
         const meta = (schema.meta ?? {});
         const schemaFile = path.join(schemasDir, `${name}.yaml`);
-        const location = artifactLocations ? artifactLocations[name] ?? null : null;
+        const location = artifactLocations ? (artifactLocations[name] ?? null) : null;
         const hasMeta = meta && Object.keys(meta).length > 0;
+        const writeInterface = stateWriterArtifactContract(name);
         artifacts.push({
             name,
             status: hasMeta ? "discovered" : "unknown_metadata",
@@ -208,13 +284,19 @@ function describeArtifactSchemas(schemasDir, schemas, model, artifactLocations)
             path: info.path || "unknown",
             location,
             artifact_type: meta.artifact_type ?? "unknown",
+            implementation_status: meta.implementation_status ?? "implemented",
             format: meta.format ?? "unknown",
             producer: meta.producer ?? "unknown",
             consumers: meta.consumers ?? "unknown",
-            fields: describeSchemaFields(schema),
+            write_interface: writeInterface,
+            fields: describeArtifactSchemaFields(schema),
         });
         if (!hasMeta) {
-            gaps.push({ scope: `artifact_schemas.${name}`, status: "unknown", message: "schema metadata is absent or unreadable" });
+            gaps.push({
+                scope: `artifact_schemas.${name}`,
+                status: "unknown",
+                message: "schema metadata is absent or unreadable",
+            });
         }
     }
     return [artifacts, gaps];
@@ -236,13 +318,10 @@ function dirExists(p) {
     }
 }
 export function buildSchemaPayload(command = "schema") {
-    const [contract, contractError] = loadDecision45Contract();
     const appModel = activeAppModel();
     const schemasDir = discoverSchemasDir(appModel);
     const schemas = loadSchemas(schemasDir);
     const gaps = [];
-    if (contractError)
-        gaps.push({ scope: "contract", status: "missing", message: contractError });
     const artifactLocationsPayload = artifactLocationContract(schemasDir, schemas);
     const artifactLocations = {};
     // cast: artifacts payload is built by query.ts over on-disk schemas/registry (IO boundary)
@@ -250,41 +329,80 @@ export function buildSchemaPayload(command = "schema") {
         artifactLocations[String(entry.name)] = entry;
     const [artifactSchemas, schemaGaps] = describeArtifactSchemas(schemasDir, schemas, appModel, artifactLocations);
     gaps.push(...schemaGaps);
-    const slashAliases = contractSection(contract, "slash_route_aliases", gaps);
-    const doctorContract = contractSection(contract, "doctor", gaps);
-    const structuredOutput = contractSection(contract, "structured_output", gaps);
-    const fieldSelection = contractSection(contract, "field_selection", gaps);
-    const isDict = (v) => v && typeof v === "object" && !Array.isArray(v);
-    const cp = contractPath();
+    const retrievalAuthority = loadStateRetrievalAuthority();
+    const profileGlossary = personalGlossaryOutputContract();
+    const authorityPath = integrationAuthorityPath();
     return {
         schemaVersion: "agentera.schema.v1",
         command,
         status: gaps.length > 0 ? "incomplete" : "ok",
         source: {
-            contract: cp,
-            contract_exists: fileExists(cp),
+            integration_authority: authorityPath,
+            integration_authority_exists: fileExists(authorityPath),
             schemas_dir: schemasDir,
             schemas_dir_exists: dirExists(schemasDir),
             schema_count: artifactSchemas.length,
             app_model: appModelPayload(appModel),
         },
         commands: describeCommands(),
+        command_vocabulary: {
+            scope: "selected_schema_projection",
+            note: "commands is a scoped schema projection; dispatcher_top_level is the complete accepted top-level runtime inventory",
+        },
+        dispatcher_top_level: {
+            authority: "packages/cli/src/cli/dispatch/commands.ts#DISPATCHER_TOP_LEVEL_COMMANDS",
+            commands: [...SCHEMA_TOP_LEVEL_COMMANDS],
+        },
+        validation: {
+            command: "agentera check validate",
+            families: [...advertisedValidateFamilyNames()],
+        },
+        state_writer: stateWriterContract(),
+        state_retrieval: {
+            authority: retrievalAuthority.authority,
+            ...projectedStateRetrieval(retrievalAuthority.retrieval),
+        },
+        integration: {
+            authority: "skills/agentera/SKILL.md",
+            active_contract: "one shared skill plus the Agentera CLI",
+            shared_skill: {
+                path: CANONICAL_SHARED_SKILL_PATH,
+                state_field: "shared_skill",
+            },
+            cli: {
+                command: "agentera",
+            },
+            personal_glossary: {
+                command: profileGlossary.command,
+                request_schema_version: profileGlossary.requestSchemaVersion,
+                output_statuses: profileGlossary.outputStatuses,
+                project_checkout: "not_required",
+            },
+            historical_import: {
+                source: "claude",
+                import_flag: "--import-source claude",
+                source_class: "historical_import",
+                default_view: "excluded",
+                all_sources_view: "--sources all",
+                sensitivity_warning: "Transcripts can contain secrets, file contents, and command output; import is local and read-only.",
+            },
+        },
         routine_state_commands: ROUTINE_STATE_COMMANDS,
         structured_output: {
-            formats: isDict(structuredOutput) ? structuredOutput.formats ?? ["json", "yaml"] : "unknown",
+            formats: ["json", "yaml"],
             fields_by_command: {
                 routine_state_commands: ROUTINE_STRUCTURED_FIELDS,
                 status: STATUS_STRUCTURED_FIELDS,
             },
         },
         field_selection: {
-            syntax: isDict(fieldSelection) ? fieldSelection.syntax ?? "--fields FIELD[,FIELD...]" : "unknown",
+            syntax: "--fields FIELD[,FIELD...]",
             retained_context: REQUIRED_SPARSE_CONTEXT_FIELDS,
-            applies_to: isDict(fieldSelection) ? fieldSelection.applies_to ?? ROUTINE_STATE_COMMANDS : "unknown",
+            applies_to: ROUTINE_STATE_COMMANDS,
         },
         slash_route_aliases: {
-            status: isDict(slashAliases) ? slashAliases.status ?? "unknown" : "unknown",
-            aliases: isDict(slashAliases) ? slashAliases.aliases ?? {} : {},
+            status: "excluded_from_cli_commands",
+            aliases: {},
             cli_commands_added: true,
             note: "Decision 43 slash-route aliases map to direct capability-name routing guidance commands in Agentera 3.0.",
         },
@@ -292,12 +410,14 @@ export function buildSchemaPayload(command = "schema") {
         artifact_locations: artifactLocationsPayload,
         doctor: {
             command: "doctor",
-            removed_command: isDict(doctorContract) ? doctorContract.removed_command ?? "unknown" : "unknown",
-            compatibility_alias: isDict(doctorContract) ? doctorContract.compatibility_alias ?? "unknown" : "unknown",
-            self_check_categories: isDict(doctorContract) ? doctorContract.owns ?? "unknown" : "unknown",
-            excludes: isDict(doctorContract) ? doctorContract.excludes ?? "unknown" : "unknown",
-            adjacent_surfaces: isDict(doctorContract) ? doctorContract.adjacent_surfaces ?? "unknown" : "unknown",
+            removed_command: "bundle-status",
+            compatibility_alias: "forbidden",
+            self_check_categories: DOCTOR_SELF_CHECK_CATEGORIES,
+            excludes: DOCTOR_EXCLUDES,
+            adjacent_surfaces: { codebase_audit: "/agentera audit" },
             signal_kinds: DOCTOR_SIGNAL_KINDS,
+            shared_skill_field: "shared_skill",
+            integration_mode: "shared_skill_and_cli_only",
         },
         gaps,
     };
@@ -307,4 +427,3 @@ export function cmdSchema(args, io) {
     emitStructured(buildSchemaPayload("schema"), args.format ?? "json", out);
     return 0;
 }
-//# sourceMappingURL=schema.js.map