@milehimikey/em 1.21.0 → 1.22.0

package/dist/cli.js

@@ -25,8 +25,9 @@ import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader, formatDiagnosticWithFile } from "./model/validate.js";
 import { buildExport, buildSliceExport, GENERATOR_VERSION } from "./emit/json.js";
 import { buildDocJsonExport } from "./emit/docJson.js";
-import { generateContract, runApiCheck, formatApiCheckText } from "./cli/api.js";
+import { generateContract, runApiCheck, formatApiCheckText, runApiSurface, formatApiSurfaceText } from "./cli/api.js";
 import { buildApiCheckJson } from "./emit/apiCheckJson.js";
+import { buildApiSurfaceJson } from "./emit/apiSurfaceJson.js";
 import { buildValidateJson, buildShapeJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
 import { buildDiffJson } from "./emit/diffJson.js";
 import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
@@ -46,10 +47,11 @@ import { observeSigners, renderRoster } from "./roster/init.js";
 import { rosterContextFor } from "./roster/context.js";
 import { computeModelKey } from "./model/qualifiedRef.js";
 import { checkRoster, formatRosterCheck, buildRosterCheckJson, grandfatheredNotice } from "./roster/check.js";
-import { applyEngagementClose, applyEngagementSet, buildNewEngagement, buildUnitIndex, effectiveTracking, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
+import { applyEngagementClose, applyEngagementSet, applyEngagementSetContext, buildNewEngagement, buildUnitIndex, effectiveTracking, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
 import { LEDGER_STATES, engagementPath, loadEngagement, readOpenEngagements } from "./cli/engagementFile.js";
-import { buildEngagementFoundationJson, buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
+import { buildEngagementBriefJson, buildEngagementFoundationJson, buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
 import { checkFoundation, formatFoundationText } from "./cli/engagementFoundation.js";
+import { engagementBriefFor, formatEngagementBriefText } from "./cli/engagementBrief.js";
 import { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
 import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli/ledgerCheck.js";
 import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
@@ -98,9 +100,10 @@ import { runDefer, runDeferFromIssue } from "./cli/defer.js";
 import { runSliceConform, runSliceConformPreview, writePreviewFindings, resolveFindingsForReport, findingsFilesOf, unruledAcrossFiles, } from "./cli/sliceConform.js";
 import { checkPrdTriage, buildCheckPrdTriageJson, renderPrdTriageMarkdown, validatePrdTriage } from "./cli/prdTriage.js";
 import { checkFindingsFile, buildCheckFindingsJson, FINDING_LOCI } from "./cli/findings.js";
+import { runBindingsCheck, buildBindingsCheckJson, renderBindingsCheckText } from "./cli/bindings.js";
 import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setModelVersion, setCertified, setEmVersion, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
 import { findCertifiedVersion, latestModelVersionNumber, modelVersionDrift, runCertifyModelVersion, runModelVersionBump, } from "./cli/modelVersion.js";
-import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile, scaffoldConstitution } from "./templates.js";
+import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile, scaffoldConstitution, SLICES_DIR_README, CONTRACTS_DIR_README, MODEL_VERSIONS_DIR_README, CONFORMANCE_BINDINGS_DIR_README, } from "./templates.js";
 import { kebabSlug } from "./util/slug.js";
 import { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, buildCiWorkflowFileMulti, buildConformWorkflowFileMulti, ciManagedBody, ciManagedBodyMulti, conformManagedBody, conformManagedBodyMulti, ciModelsFromManifest, describeOtherModels, describeSetChange, fileBlockModels, planCiFile, refreshCiPullRequestPaths, applyCiPullRequestPathsRefresh, applyCiFile, findUnsafeCiInitArg, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./cli/ciInit.js";
 import { resolveRepoRoot, detectUpgrade, applyUpgrade, checkUpgrade } from "./cli/upgrade.js";
@@ -162,7 +165,10 @@ program
     .command("scaffold")
     .description("scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md, and " +
     "constitution.md (the implementation constitution — skipped, with a note, in a spec-kit " +
-    "project, where `.specify/memory/constitution.md` IS that document) " +
+    "project, where `.specify/memory/constitution.md` IS that document), plus the standard " +
+    "slices/, contracts/, model-versions/ and conformance/bindings/ directories (each seeded " +
+    "with a one-line README naming what lands there and which command writes it, instead of " +
+    "a .gitkeep) " +
     "(see docs/cli.md — for just a starter .em, use `em init`; for a multi-model project, " +
     "pass --under to nest it under a shared parent directory)")
     .argument("<name>", "model display name — kebab-cased for the directory and file names, used as-is for titles/prose")
@@ -186,6 +192,20 @@ program
     writeFileSync(join(dirPath, `${slugName}.em`), starterEmFor(name));
     writeFileSync(join(dirPath, "README.md"), scaffoldReadme(name, slugName));
     writeFileSync(join(dirPath, STATE_FILE_NAME), scaffoldStateFile(name, slugName, today, PKG_VERSION));
+    // GH #453: the full standardized model-directory family, not just the four files above —
+    // every doc-aware command eventually writes into one of these. Git doesn't track empty
+    // directories, so each gets a one-line README (never a .gitkeep) naming what lands there
+    // and which command writes it.
+    await mkdir(join(dirPath, "slices"), { recursive: true });
+    writeFileSync(join(dirPath, "slices", "README.md"), SLICES_DIR_README);
+    await mkdir(join(dirPath, "contracts"), { recursive: true });
+    writeFileSync(join(dirPath, "contracts", "README.md"), CONTRACTS_DIR_README);
+    await mkdir(join(dirPath, "model-versions"), { recursive: true });
+    writeFileSync(join(dirPath, "model-versions", "README.md"), MODEL_VERSIONS_DIR_README);
+    // conformance/bindings/ (GH #449) — creating it also creates its conformance/ parent, which
+    // otherwise only appears once the conform phase writes its first report/findings file.
+    await mkdir(join(dirPath, "conformance", "bindings"), { recursive: true });
+    writeFileSync(join(dirPath, "conformance", "bindings", "README.md"), CONFORMANCE_BINDINGS_DIR_README);
     // MIL-202: the implementation constitution. One document per project, never two — in a
     // spec-kit project `.specify/memory/constitution.md` already IS that slot, so em defers to it
     // and writes nothing rather than seeding a second, competing copy beside the model. Same
@@ -442,6 +462,25 @@ api
     if (!outcome.report.current)
         process.exitCode = 1;
 });
+api
+    .command("surface")
+    .description("the model's public commands, events, views and reachable declared types as a versioned " +
+    "JSON document for companion tools (GH #448, see docs/cli.md)")
+    .argument("<file>", "input .em file")
+    .option("--json", "print a JSON document instead of the text listing (see docs/cli.md)")
+    .action((file, opts) => {
+    const outcome = runApiSurface(file);
+    printDiagnostics(outcome.diagnostics);
+    if (!outcome.ok) {
+        console.error(outcome.message);
+        process.exit(1);
+    }
+    if (opts.json)
+        process.stdout.write(buildApiSurfaceJson(outcome.report) + "\n");
+    else
+        for (const line of formatApiSurfaceText(outcome.report))
+            console.log(line);
+});
 program
     .command("typespec")
     .description("DEPRECATED alias of `em api generate --stdout` (use em api generate)")
@@ -1739,6 +1778,44 @@ conformFindings
     if (!result.ok)
         process.exit(1);
 });
+const conform = program.command("conform").description("file-contract conformance checks (advisory only, GH #449 — never wired into validate/--slice-ready)");
+const conformBindings = conform.command("bindings").description("per-slice bindings manifests (conformance/bindings/<slice-key>.yaml, see docs/bindings.md)");
+conformBindings
+    .command("check")
+    .description("verify every per-slice bindings manifest (conformance/bindings/<slice-key>.yaml, see " +
+    "docs/bindings.md): each bound element's `ref` resolves against the compiled model, and " +
+    "each bound `file` exists under --repo and contains its `identifier` as a plain substring " +
+    "(grep-level only, never code-parsed — language-agnostic). Distinct failure kinds: an " +
+    "unknown `--slice` key, a missing bindings file, malformed YAML, an unknown slice named " +
+    "inside a file, and an unknown element ref. Advisory only — exit code stays 0 unless " +
+    "--exit-code is given and a binding failed (the opt-in CI gate, same posture as `em refs " +
+    "--reachable-from`).")
+    .argument("<file>", "input .em file")
+    .requiredOption("--repo <path>", "path to the target codebase (bound `file`s resolve relative to it; never required to be a git repository)")
+    .option("--slice <key>", "check only this slice's bindings file (default: every conformance/bindings/*.yaml)")
+    .option("--json", "print a JSON document instead of the text report")
+    .option("--exit-code", "exit 1 if any binding failed (git-diff convention) — the opt-in CI gate")
+    .action((file, opts) => {
+    const { model, diagnostics, refs } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("em conform bindings check: fix the model's errors above first");
+        process.exit(1);
+    }
+    const sliceKey = opts.slice !== undefined ? resolveSliceOrExit("em conform bindings check", model, refs, opts.slice) : undefined;
+    const result = runBindingsCheck(refs, dirname(file), opts.repo, sliceKey);
+    if (opts.json) {
+        console.log(buildBindingsCheckJson(result));
+    }
+    else {
+        console.log(renderBindingsCheckText(result));
+    }
+    // Same rationale as `em diff`/`em api check`'s --exit-code: set the code rather than
+    // process.exit() so a large --json document piped downstream isn't truncated, and so this
+    // advisory check NEVER fails a run by default (GH #449 — opt-in CI gate only).
+    if (opts.exitCode && !result.ok)
+        process.exitCode = 1;
+});
 const discover = program.command("discover").description("checks for the discover skill's records (GH #295)");
 discover
     .command("triage-check")
@@ -2462,7 +2539,7 @@ program
     // merged `sliceFacts` above (which spans every input file when several are given).
     const conformance = compiled.map(({ file }) => {
         const facts = factsByFile.get(file) ?? [];
-        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn, shipped: f.shipped }));
+        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn, shipped: f.shipped, file: f.sliceFile }));
         return resolveConformanceEntry(file, opts.repo, sliceDocFacts);
     });
     // MIL-218: one model-version entry per input file.
@@ -2724,6 +2801,7 @@ engagement
     .option("--by <name>", "who created the engagement (createdBy)")
     .option("--tracking <key>", "an issue-tracker key or URL the slice PRs cite (a slice doc's own tracking: wins)")
     .option("--pr-title <template>", "PR title template for the slice PRs; {key} = tracking key, {slice} = slice name, {sliceKey} = slice key (default \"{key}: {slice}\", or \"{slice}\" without a key)")
+    .option("--context-doc <path>", "repo-relative path to a document implementers need beyond the slice doc — the constitution, an NFR doc, an ADR (repeatable; GH #455)", (value, previous) => [...previous, value], [])
     .option("--force", "overwrite an existing engagement file with this slug")
     .action((file, slug, opts) => {
     const fail = (m) => {
@@ -2743,7 +2821,7 @@ engagement
     const parallel = /^\d+$/.test(opts.parallel) ? Number(opts.parallel) : NaN;
     const { model, refs } = compileFile(file);
     const path = engagementPath(file, slug);
-    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, prTitle: opts.prTitle ?? null, created: localIsoDate() });
+    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, prTitle: opts.prTitle ?? null, context: opts.contextDoc, created: localIsoDate() });
     if (!result.ok)
         return fail(result.message);
     if (existsSync(path) && !opts.force)
@@ -2821,22 +2899,76 @@ engagement
     if (!check.ok)
         process.exitCode = 1;
 });
+engagement
+    .command("brief")
+    .description("GH #454: a deterministic, self-contained per-slice work brief for implementers em does not " +
+    "control (a ticket-driven cloud agent) — the bound slice doc verbatim (or the model's own " +
+    "elements when there is none), model context from the edge list, the public-contract " +
+    "surface, a definition-of-done (bindings manifest skeleton + conform check + isolation + PR " +
+    "title), and the engagement's context: documents. One brief per engagement slice unless " +
+    "--slice narrows it")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .option("--slice <key>", "only this slice's brief (export key, display name, or unique prefix)")
+    .option("--inline-context", "embed each context document's full text instead of just its path")
+    .option("--json", "print a JSON document instead of text (same document as the MCP engagement_brief tool)")
+    .action((file, slug, opts) => {
+    const { model, refs } = compileFile(file);
+    // GH #237: an input that resolves to no slice goes through as typed, so the engagement's own
+    // "is not in engagement" refusal (which names what the Ledger holds) still speaks.
+    let sliceKey = null;
+    if (opts.slice !== undefined) {
+        const resolved = resolveSliceKey(model, refs, opts.slice);
+        sliceKey = resolved.ok ? resolved.key : opts.slice;
+    }
+    const result = engagementBriefFor({ file, model, refs, baseDir: dirname(file) }, slug, { sliceKey, inlineContext: opts.inlineContext === true });
+    if (!result.ok) {
+        console.error(`em engagement brief: ${result.message}`);
+        process.exit(1);
+    }
+    process.stdout.write((opts.json ? buildEngagementBriefJson(result.brief) : formatEngagementBriefText(result.brief)) + "\n");
+});
 engagement
     .command("set")
     .description("the only write path to the Ledger: set one slice's state (and optionally branch/base/pr); " +
-    "idempotent; merged is terminal; --state held records a human hold")
+    "idempotent; merged is terminal; --state held records a human hold. Or, on its own (no slice " +
+    "key), --context-doc replaces the engagement-level context: list (GH #455)")
     .argument("<file>", "input .em file")
     .argument("<slug>", "engagement slug")
-    .argument("<key>", "slice export key")
-    .requiredOption("--state <state>", `one of: ${LEDGER_STATES.join(" | ")}`)
+    .argument("[key]", "slice export key (omit when using --context-doc alone)")
+    .option("--state <state>", `one of: ${LEDGER_STATES.join(" | ")}`)
     .option("--branch <name>", "the slice's branch")
     .option("--base <name>", "the branch the slice's PR targets")
     .option("--pr <url>", "the slice's PR URL")
+    .option("--context-doc <path>", "repo-relative path to a document implementers need beyond the slice doc (repeatable; replaces the whole engagement-level context: list; GH #455)", (value, previous) => [...previous, value], [])
     .action((file, slug, key, opts) => {
     const fail = (m) => {
         console.error(`em engagement set: ${m}`);
         process.exit(1);
     };
+    const sliceFields = opts.state !== undefined || opts.branch !== undefined || opts.base !== undefined || opts.pr !== undefined;
+    if (opts.contextDoc.length > 0) {
+        if (key !== undefined || sliceFields) {
+            return fail("--context-doc sets the engagement-level context: list on its own — pass it without a slice key or --state/--branch/--base/--pr");
+        }
+        const loaded = loadEngagement(file, slug);
+        if (!loaded.ok)
+            return fail(loaded.message);
+        const result = applyEngagementSetContext(slug, loaded.text, loaded.file, opts.contextDoc);
+        if (!result.ok)
+            return fail(result.message);
+        if (!result.changed) {
+            console.log(`no change: context is already [${result.context.join(", ")}] (${loaded.path})`);
+            return;
+        }
+        writeFileSync(loaded.path, result.text);
+        console.log(`set context: ${result.context.length} path${result.context.length === 1 ? "" : "s"} (${loaded.path})`);
+        return;
+    }
+    if (!key)
+        return fail("a slice export key is required (or pass --context-doc to set the engagement-level context: list)");
+    if (!opts.state)
+        return fail("--state is required when setting a slice");
     const loaded = loadEngagement(file, slug);
     if (!loaded.ok)
         return fail(loaded.message);
@@ -2846,7 +2978,7 @@ engagement
     const resolved = resolveSliceKey(model, refs, key);
     if (resolved.ok)
         key = resolved.key;
-    const result = applyEngagementSet({ file, model, refs, baseDir: dirname(file) }, slug, loaded.text, loaded.file, { key, ...opts });
+    const result = applyEngagementSet({ file, model, refs, baseDir: dirname(file) }, slug, loaded.text, loaded.file, { key, state: opts.state, branch: opts.branch, base: opts.base, pr: opts.pr });
     if (!result.ok)
         return fail(result.message);
     if (!result.changed) {