@odla-ai/cli 0.21.0 → 0.22.1

package/README.md

@@ -37,6 +37,26 @@ npx @odla-ai/cli runbook list                                      # what exists
 Reading works for any signed-in developer and needs no `odla.config.mjs` — the
 advice is most useful before there is a project.
 
+Runbooks tell an agent how to operate; PM tells every agent what this project is
+trying to prove, what is active, what was decided, and what is broken. Once the
+app is registered, start each session by reading its doing tasks, open bugs and
+goals, and recent decisions:
+
+```bash
+npx odla-ai pm task list --app <appId> --column doing
+npx odla-ai pm bug list --app <appId> --status open
+npx odla-ai pm goal list --app <appId> --status open
+npx odla-ai pm decision list --app <appId> --limit 20
+```
+
+Read the active task, linked goal, and comments before changing code. Without
+`--app`, list commands span every project the account co-owns, which is the
+right first view when coordinating several efforts; scope every write to the
+exact `appId` from that project's config. PM requires a registered app. Before
+the first provision, use a focused commit/checkpoint, then initialize PM and
+backfill that evidence immediately after registration. Never use a parallel
+status diary or put a secret in PM.
+
 **Runbooks are procedure; JSDoc is API.** What a function takes, returns, and
 guarantees is documented on the export itself, ships in the installed
 `.d.ts`, and renders per package at <https://odla.ai/docs>. A runbook will tell
@@ -93,11 +113,14 @@ npx @odla-ai/cli init --app-id my-app --name "My App"
 ```
 
 For a project you keep working in, install it as a dev dependency so the
-shorter `npx odla-ai` form works and the version is pinned by your lockfile:
+shorter `npx odla-ai` form works. ODLA is under active development: use a normal
+dependency declaration, commit the lockfile, and let `npm ci` reproduce the
+resolved graph:
 
 ```bash
-npm view @odla-ai/cli@0.16.6 version
-npm i -D --save-exact @odla-ai/cli@0.16.6
+npm view @odla-ai/cli version
+npm i -D @odla-ai/cli
+npm ls @odla-ai/cli
 ```
 
 ## Prerequisites
@@ -360,8 +383,8 @@ rolling-window/age-out, quota-backoff, retention/purge, or provider-derived
 mutation-id control. Public health remains aggregate rather than per calendar.
 
 The bundled build/migration skills add a passive pre-ship gate with
-`@odla-ai/security`: after the exact-version availability check, run
-`npm i -D --save-exact @odla-ai/security@0.3.1`, then
+`@odla-ai/security`: install it with a normal development range, commit the
+lockfile, then run `npm i -D @odla-ai/security`, followed by
 `npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical`.
 The passive scan remains a separate binary: it makes no model calls and does
 not execute target code. After explicit redacted-source approval,
@@ -385,12 +408,11 @@ a conservative `Retry-After`. A provider-side `429` uses the sanitized
 carries a bounded `Retry-After` only when the upstream supplied one. The CLI
 does not echo arbitrary response text or silently change the admin-selected
 model.
-Before installing the exact release, require
-`npm view @odla-ai/security@0.3.1 version` to succeed before installation. An
-exact-version `E404` means the release is unavailable, not that the security
-preflight passed, and does not prove the package name is absent. odla's own
-engineering environment uses an equivalent internal gate; customer projects
-should use the published `odla-security` command above.
+Confirm `npm view @odla-ai/security version` succeeds and record the installed
+version from `npm ls @odla-ai/security` with the scan evidence. A registry
+failure blocks the preflight; it is not a clean scan. odla's own engineering
+environment uses an equivalent internal gate; customer projects should use the
+published `odla-security` command above.
 
 For a server-side, commit-pinned review, connect one repository through the
 source-read-only odla GitHub App. The CLI infers `owner/name` from a safe GitHub HTTPS

package/dist/bin.cjs

@@ -7799,13 +7799,154 @@ ${env}: credentials are already saved; retry "odla-ai secrets push --env ${env}$
   }
 }
 
+// src/record.ts
+var import_node_fs13 = require("fs");
+var import_node_process8 = __toESM(require("process"), 1);
+
+// src/surface.ts
+var PM_ACTIONS = {
+  list: {},
+  add: {},
+  create: {},
+  get: {},
+  set: {},
+  update: {},
+  status: {},
+  move: {},
+  done: {},
+  comment: {},
+  comments: {},
+  rm: {},
+  delete: {}
+};
+var PM_ENTITIES = Object.fromEntries(
+  ["goal", "conformance", "task", "kanban", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
+);
+var COMMAND_SURFACE = {
+  admin: {
+    ai: {
+      show: {},
+      set: {},
+      credentials: {},
+      models: {},
+      usage: {},
+      audit: {},
+      credential: { set: {} }
+    }
+  },
+  app: {
+    archive: {},
+    restore: {},
+    export: {},
+    import: {},
+    rename: {},
+    "refresh-sandbox": {},
+    "go-live": {},
+    promote: {},
+    owners: { list: {}, add: {}, remove: {} }
+  },
+  calendar: { status: {}, calendars: {}, connect: {}, disconnect: {} },
+  capabilities: {},
+  code: { connect: {} },
+  doctor: {},
+  help: {},
+  init: {},
+  pm: PM_ENTITIES,
+  provision: {},
+  runbook: {
+    ask: {},
+    search: {},
+    impact: {},
+    list: {},
+    get: {},
+    cat: {},
+    new: {},
+    edit: {},
+    comment: {},
+    import: {},
+    visibility: {},
+    publish: {},
+    archive: {},
+    history: {},
+    revert: {},
+    rm: {},
+    lint: {}
+  },
+  secrets: { push: {}, set: {}, "set-clerk-key": {} },
+  security: {
+    plan: {},
+    sources: {},
+    run: {},
+    status: {},
+    report: {},
+    github: { connect: {}, disconnect: {} }
+  },
+  setup: {},
+  skill: { install: {} },
+  smoke: {},
+  version: {},
+  whoami: {}
+};
+function acceptedAfter(path) {
+  let node = COMMAND_SURFACE;
+  for (const word of path) {
+    node = node?.[word];
+    if (!node) return [];
+  }
+  return Object.keys(node).sort();
+}
+function validateInvocation(words2) {
+  let node = COMMAND_SURFACE;
+  const walked = [];
+  for (const word of words2) {
+    if (Object.keys(node).length === 0) return null;
+    const next = node[word];
+    if (!next) return { validPrefix: walked.join(" "), word, accepted: Object.keys(node).sort() };
+    walked.push(word);
+    node = next;
+  }
+  return null;
+}
+function describeProblem(problem) {
+  const where = problem.validPrefix ? `after "${problem.validPrefix}"` : "as a command";
+  return `"${problem.word}" is not accepted ${where} \u2014 try: ${problem.accepted.join(", ")}`;
+}
+function invocationPath(words2) {
+  let node = COMMAND_SURFACE;
+  const path = [];
+  for (const word of words2) {
+    const next = node[word];
+    if (!next) break;
+    path.push(word);
+    node = next;
+    if (Object.keys(node).length === 0) break;
+  }
+  return path;
+}
+
+// src/record.ts
+function recordInvocation(parsed) {
+  const file = import_node_process8.default.env.ODLA_CLI_RECORD;
+  if (!file) return;
+  try {
+    const entry = {
+      path: invocationPath(parsed.positionals),
+      options: Object.keys(parsed.options).sort()
+    };
+    if (!entry.path.length) return;
+    (0, import_node_fs13.appendFileSync)(file, `${JSON.stringify(entry)}
+`);
+  } catch {
+  }
+}
+
 // src/runbook-command.ts
-var import_node_fs17 = require("fs");
+var import_node_fs18 = require("fs");
 var import_node_path14 = require("path");
-var import_node_process9 = __toESM(require("process"), 1);
+var import_node_process10 = __toESM(require("process"), 1);
 
 // src/runbook-actions.ts
-var import_node_fs13 = require("fs");
+var import_node_fs14 = require("fs");
 
 // src/runbook-requires.ts
 var SPEC = /^(@?[\w./-]+?)@(\d+\.\d+\.\d+(?:[\w.-]*)?)$/;
@@ -7890,7 +8031,7 @@ async function bySlug(ctx, slug) {
 function readBody(file, inline) {
   if (inline !== void 0) return inline;
   if (file === void 0) throw new Error("supply the new text with --file <path>, --file - (stdin), or --body");
-  return (0, import_node_fs13.readFileSync)(file === "-" ? 0 : file, "utf8");
+  return (0, import_node_fs14.readFileSync)(file === "-" ? 0 : file, "utf8");
 }
 var stamp = (ms) => ms ? new Date(ms).toISOString().slice(0, 16).replace("T", " ") : "";
 async function runbookList(ctx, all, query) {
@@ -7977,7 +8118,7 @@ async function runbookRemove(ctx, slug) {
 }
 
 // src/runbook-import.ts
-var import_node_fs14 = require("fs");
+var import_node_fs15 = require("fs");
 var import_node_path11 = require("path");
 function parseRunbook(text, slug) {
   let rest = text;
@@ -8003,12 +8144,12 @@ function parseRunbook(text, slug) {
   };
 }
 function readRunbookDir(dir) {
-  if (!(0, import_node_fs14.statSync)(dir, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`not a directory: ${dir}`);
-  const files = (0, import_node_fs14.readdirSync)(dir).filter((f) => f.endsWith(".md")).sort();
+  if (!(0, import_node_fs15.statSync)(dir, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`not a directory: ${dir}`);
+  const files = (0, import_node_fs15.readdirSync)(dir).filter((f) => f.endsWith(".md")).sort();
   if (!files.length) throw new Error(`no .md files in ${dir}`);
   return files.map((file) => {
     const slug = (0, import_node_path11.basename)(file, ".md");
-    const parsed = parseRunbook((0, import_node_fs14.readFileSync)((0, import_node_path11.join)(dir, file), "utf8"), slug);
+    const parsed = parseRunbook((0, import_node_fs15.readFileSync)((0, import_node_path11.join)(dir, file), "utf8"), slug);
     return { file, slug, ...parsed, words: parsed.body.split(/\s+/).filter(Boolean).length };
   });
 }
@@ -8080,7 +8221,7 @@ async function upsert(ctx, r, visibility) {
 
 // src/runbook-impact.ts
 var import_node_child_process7 = require("child_process");
-var import_node_fs15 = require("fs");
+var import_node_fs16 = require("fs");
 var import_node_path12 = require("path");
 
 // src/runbook-impact-scan.ts
@@ -8251,9 +8392,9 @@ ${body.split("\n").map((line) => `+${line}`).join("\n")}
 function manifestLabeller(root) {
   return (workspace) => {
     const manifest = (0, import_node_path12.join)(root, workspace, "package.json");
-    if (!(0, import_node_fs15.existsSync)(manifest)) return void 0;
+    if (!(0, import_node_fs16.existsSync)(manifest)) return void 0;
     try {
-      const name = JSON.parse((0, import_node_fs15.readFileSync)(manifest, "utf8")).name;
+      const name = JSON.parse((0, import_node_fs16.readFileSync)(manifest, "utf8")).name;
       return typeof name === "string" ? name : void 0;
     } catch {
       return void 0;
@@ -8320,7 +8461,7 @@ function report2(ctx, impacts) {
 async function runbookImpact(ctx, options, deps = {}) {
   const cwd = deps.cwd ?? process.cwd();
   const runGit = deps.runGit ?? gitRunner(cwd);
-  const read2 = deps.readRepoFile ?? ((path) => (0, import_node_fs15.readFileSync)((0, import_node_path12.join)(cwd, path), "utf8"));
+  const read2 = deps.readRepoFile ?? ((path) => (0, import_node_fs16.readFileSync)((0, import_node_path12.join)(cwd, path), "utf8"));
   const surfaces = changedSurfaces(collectDiff(runGit, options.base, read2), manifestLabeller(cwd));
   if (!surfaces.length) {
     return ctx.out.log(
@@ -8332,115 +8473,6 @@ async function runbookImpact(ctx, options, deps = {}) {
   report2(ctx, impacts);
 }
 
-// src/surface.ts
-var PM_ACTIONS = {
-  list: {},
-  add: {},
-  create: {},
-  get: {},
-  set: {},
-  update: {},
-  status: {},
-  move: {},
-  done: {},
-  comment: {},
-  comments: {},
-  rm: {},
-  delete: {}
-};
-var PM_ENTITIES = Object.fromEntries(
-  ["goal", "conformance", "task", "kanban", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
-);
-var COMMAND_SURFACE = {
-  admin: {
-    ai: {
-      show: {},
-      set: {},
-      credentials: {},
-      models: {},
-      usage: {},
-      audit: {},
-      credential: { set: {} }
-    }
-  },
-  app: {
-    archive: {},
-    restore: {},
-    export: {},
-    import: {},
-    rename: {},
-    "refresh-sandbox": {},
-    "go-live": {},
-    promote: {},
-    owners: { list: {}, add: {}, remove: {} }
-  },
-  calendar: { status: {}, calendars: {}, connect: {}, disconnect: {} },
-  capabilities: {},
-  code: { connect: {} },
-  doctor: {},
-  help: {},
-  init: {},
-  pm: PM_ENTITIES,
-  provision: {},
-  runbook: {
-    ask: {},
-    search: {},
-    impact: {},
-    list: {},
-    get: {},
-    cat: {},
-    new: {},
-    edit: {},
-    comment: {},
-    import: {},
-    visibility: {},
-    publish: {},
-    archive: {},
-    history: {},
-    revert: {},
-    rm: {},
-    lint: {}
-  },
-  secrets: { push: {}, set: {}, "set-clerk-key": {} },
-  security: {
-    plan: {},
-    sources: {},
-    run: {},
-    status: {},
-    report: {},
-    github: { connect: {}, disconnect: {} }
-  },
-  setup: {},
-  skill: { install: {} },
-  smoke: {},
-  version: {},
-  whoami: {}
-};
-function acceptedAfter(path) {
-  let node = COMMAND_SURFACE;
-  for (const word of path) {
-    node = node?.[word];
-    if (!node) return [];
-  }
-  return Object.keys(node).sort();
-}
-function validateInvocation(words2) {
-  let node = COMMAND_SURFACE;
-  const walked = [];
-  for (const word of words2) {
-    if (Object.keys(node).length === 0) return null;
-    const next = node[word];
-    if (!next) return { validPrefix: walked.join(" "), word, accepted: Object.keys(node).sort() };
-    walked.push(word);
-    node = next;
-  }
-  return null;
-}
-function describeProblem(problem) {
-  const where = problem.validPrefix ? `after "${problem.validPrefix}"` : "as a command";
-  return `"${problem.word}" is not accepted ${where} \u2014 try: ${problem.accepted.join(", ")}`;
-}
-
 // src/runbook-lint.ts
 function invocationsIn(body) {
   const re = /(`|npx[^\S\n]+)?(?:@odla-ai\/cli(?:@[\w.-]+)?|odla-ai)((?:[^\S\n]+[a-z][\w-]*)+)/g;
@@ -8562,12 +8594,12 @@ async function runbookComment(ctx, slug, body) {
 
 // src/runbook-editor.ts
 var import_node_child_process8 = require("child_process");
-var import_node_fs16 = require("fs");
+var import_node_fs17 = require("fs");
 var import_node_os4 = require("os");
 var import_node_path13 = require("path");
-var import_node_process8 = __toESM(require("process"), 1);
+var import_node_process9 = __toESM(require("process"), 1);
 var EDITOR_ENV = ["ODLA_EDITOR", "VISUAL", "EDITOR"];
-function resolveEditor(env = import_node_process8.default.env) {
+function resolveEditor(env = import_node_process9.default.env) {
   for (const name of EDITOR_ENV) {
     const value = env[name];
     if (value && value.trim()) return value.trim();
@@ -8581,8 +8613,8 @@ function defaultRun(command, path) {
   return result.status ?? 0;
 }
 function editText(initial, slug, deps = {}) {
-  const env = deps.env ?? import_node_process8.default.env;
-  const interactive = deps.interactive ?? (() => Boolean(import_node_process8.default.stdin.isTTY));
+  const env = deps.env ?? import_node_process9.default.env;
+  const interactive = deps.interactive ?? (() => Boolean(import_node_process9.default.stdin.isTTY));
   const editor = resolveEditor(env);
   if (!editor)
     throw new Error(
@@ -8590,16 +8622,16 @@ function editText(initial, slug, deps = {}) {
     );
   if (!interactive())
     throw new Error(`cannot open an editor without a terminal \u2014 pass --file <path> or --body "\u2026" instead`);
-  const dir = (0, import_node_fs16.mkdtempSync)((0, import_node_path13.join)((0, import_node_os4.tmpdir)(), "odla-runbook-"));
+  const dir = (0, import_node_fs17.mkdtempSync)((0, import_node_path13.join)((0, import_node_os4.tmpdir)(), "odla-runbook-"));
   const file = (0, import_node_path13.join)(dir, `${slug}.md`);
   try {
-    (0, import_node_fs16.writeFileSync)(file, initial, { mode: 384 });
+    (0, import_node_fs17.writeFileSync)(file, initial, { mode: 384 });
     const code = defaultRunOrInjected(deps)(editor, file);
     if (code !== 0) throw new Error(`editor "${editor}" exited with ${code}; nothing was written`);
-    const edited = (0, import_node_fs16.readFileSync)(file, "utf8");
+    const edited = (0, import_node_fs17.readFileSync)(file, "utf8");
     return edited === initial ? null : edited;
   } finally {
-    (0, import_node_fs16.rmSync)(dir, { recursive: true, force: true });
+    (0, import_node_fs17.rmSync)(dir, { recursive: true, force: true });
   }
 }
 var defaultRunOrInjected = (deps) => deps.run ?? defaultRun;
@@ -8699,11 +8731,11 @@ var WRITES = /* @__PURE__ */ new Set(["new", "edit", "publish", "archive", "visi
 var CONFIG_FREE = /* @__PURE__ */ new Set(["list", "search", "ask", "get", "cat", "history", "impact", "lint"]);
 async function loadOrDefaultConfig(configPath, action, appId) {
   const projectScoped = appId !== void 0;
-  if (!projectScoped && CONFIG_FREE.has(action) && !(0, import_node_fs17.existsSync)((0, import_node_path14.resolve)(configPath))) {
-    const rootDir = import_node_process9.default.cwd();
+  if (!projectScoped && CONFIG_FREE.has(action) && !(0, import_node_fs18.existsSync)((0, import_node_path14.resolve)(configPath))) {
+    const rootDir = import_node_process10.default.cwd();
     return {
       configPath,
-      platformUrl: import_node_process9.default.env.ODLA_PLATFORM_URL ?? "https://odla.ai",
+      platformUrl: import_node_process10.default.env.ODLA_PLATFORM_URL ?? "https://odla.ai",
       rootDir,
       app: { id: "", name: "" },
       local: { tokenFile: (0, import_node_path14.join)(rootDir, ".odla/dev-token.json") }
@@ -9553,6 +9585,7 @@ function exitCodeFor(err) {
 }
 async function runCli(argv = process.argv.slice(2), dependencies = {}) {
   const parsed = parseArgv(argv);
+  recordInvocation(parsed);
   const command = parsed.positionals[0] ?? "help";
   if (command === "version" || command === "-v" || parsed.options.version === true) {
     assertArgs(parsed, ["version"], 1);