@odla-ai/cli 0.18.0 → 0.20.0

package/README.md

@@ -66,6 +66,23 @@ Platform runbook edits need admin or the `platform:runbook:write` capability,
 which the CLI requests for you; a plain handshake token is never admin by
 design, and `odla-ai whoami` reports what this terminal actually holds.
 
+**Is the corpus itself still true?**
+
+```bash
+npx odla-ai runbook lint
+```
+
+Because a runbook is edited without a release, its text can name a command that
+only a newer CLI has — and no gate in any repository can see that, since the
+text is a row in a database rather than a file. `lint` closes that: it holds
+every `odla-ai …` command the runbooks name against this CLI's actual command
+surface, and against the minimum versions each runbook declares in `requires`.
+
+A runbook may record the versions its steps assume, as `name@version` specs read
+as minimums (`@odla-ai/cli@0.18.0`). When yours is older, `runbook get` says so
+on **stderr** — never stdout, so piping the procedure into an agent still yields
+the procedure and nothing else.
+
 ## Install
 
 No install needed — the package ships a single `odla-ai` binary, so npx can run
@@ -109,6 +126,7 @@ npx odla-ai runbook search "restore a tenant" --limit 5
 npx odla-ai runbook get release
 npx odla-ai runbook list
 npx odla-ai runbook impact --base origin/main
+npx odla-ai runbook lint
 npx odla-ai runbook edit db --note "what changed"
 npx odla-ai runbook comment release --body "step 4 no longer applies"
 npx odla-ai whoami
@@ -118,7 +136,6 @@ npx odla-ai doctor
 npx odla-ai calendar status --env dev
 npx odla-ai calendar calendars --env dev
 npx odla-ai calendar connect --env dev
-npx odla-ai calendar resync --env dev
 npx odla-ai calendar disconnect --env dev --yes
 npx odla-ai capabilities --json
 npx odla-ai code connect --platform https://odla.ai --app-id my-app --env dev --email owner@example.com
@@ -318,19 +335,18 @@ agent automation. Once connected, `calendar calendars` lists ids visible to the
 Google identity so the checked-in selection can be refined. `calendar connect`
 applies the checked-in booking-page setting and starts consent when the
 connection is absent, failed, disconnected, or degraded (so an agent can
-repair revoked credentials); a healthy connection is reused. A `needs_sync`
-connection already has provider credentials, so connect/provision resyncs it
-without requesting Google consent again; an existing authorization or initial
-sync is awaited instead of creating a duplicate attempt.
-`calendar resync` asks the hosted connector to sync immediately; `calendar
-disconnect --yes` stops watches and deletes this app/environment connection's
-encrypted platform token and cursors without purging retained mirror rows,
-which may therefore remain readable but stale. It does not revoke the shared
-user-to-Google-OAuth-project grant, because that could invalidate other odla
-connections for the same user. A future explicitly global revoke command would
-need cross-connection accounting and warning. Production resync requires
-`--yes`, as does a direct production connect. None of these commands accepts a
-Google authorization code, client secret, access token, or refresh token.
+repair revoked credentials); a healthy connection is reused. A connection that
+already holds provider credentials is reused without requesting Google consent
+again, and an in-flight authorization is awaited rather than duplicated.
+
+Nothing syncs: Google Calendar is the source of truth and odla stores no events
+and no attendees, so there is no resync to ask for. `calendar disconnect --yes`
+deletes this app/environment connection's encrypted platform token. It does not
+revoke the shared user-to-Google-OAuth-project grant, because that could
+invalidate other odla connections for the same user. A future explicitly global
+revoke command would need cross-connection accounting and warning. A direct
+production connect requires `--yes`. None of these commands accepts a Google
+authorization code, client secret, access token, or refresh token.
 
 The SDK uses the existing server-side db values (`ODLA_ENDPOINT`,
 `ODLA_TENANT`, `ODLA_API_KEY`), so calendar adds no Worker secret. Never expose

package/dist/bin.cjs

@@ -6435,11 +6435,12 @@ Usage:
   odla-ai runbook ask "<question>" [--app <id>] [--all] [--json]
   odla-ai runbook search "<question>" [--app <id>] [--all] [--limit <n>] [--json]
   odla-ai runbook impact [--base origin/main] [--app <id>] [--all] [--limit <n>] [--json]
+  odla-ai runbook lint [--app <id>] [--all] [--json]
   odla-ai runbook list [--app <id>] [--all] [--q <text>] [--json]
   odla-ai runbook comment <slug> --body "..." [--app <id>]
   odla-ai runbook get <slug> [--app <id>]
-  odla-ai runbook new <slug> --title <t> --file <path|-> [--summary <s>] [--app <id>]
-  odla-ai runbook edit <slug> [--file <path|->|--body "..."] [--note <why>] [--app <id>]
+  odla-ai runbook new <slug> --title <t> --file <path|-> [--summary <s>] [--requires <specs>] [--app <id>]
+  odla-ai runbook edit <slug> [--file <path|->|--body "..."] [--note <why>] [--requires <specs>] [--app <id>]
   odla-ai runbook import <dir> [--visibility operator|admin] [--dry-run] [--app <id>]
   odla-ai runbook publish <slug> [--app <id>]
   odla-ai runbook visibility <slug> <operator|admin> [--app <id>]
@@ -6481,7 +6482,10 @@ Commands:
                "search" the passages behind it; "get" the whole document.
                "impact" diffs your working tree against a base ref and names the
                runbooks that describe what you changed \u2014 run it after touching a
-               package's exported API or JSDoc, or a Studio surface. A wrong step
+               package's exported API or JSDoc, or a Studio surface. "lint"
+               checks the corpus the other way: every odla-ai command the
+               runbooks name is held against this CLI's real command surface,
+               and against the minimum versions each runbook declares. A wrong step
                is fixed with "edit", which takes effect immediately: a runbook is
                a row, not a release. Runbooks describe PROCEDURE; what an export
                does and what it guarantees is JSDoc, rendered per package at
@@ -7802,6 +7806,55 @@ var import_node_process9 = __toESM(require("process"), 1);
 
 // src/runbook-actions.ts
 var import_node_fs13 = require("fs");
+
+// src/runbook-requires.ts
+var SPEC = /^(@?[\w./-]+?)@(\d+\.\d+\.\d+(?:[\w.-]*)?)$/;
+function parseRequires(value) {
+  if (!value) return [];
+  const out = [];
+  for (const token of value.split(/[\s,]+/).filter(Boolean)) {
+    const match = SPEC.exec(token);
+    if (match?.[1] && match[2]) out.push({ name: match[1], min: match[2] });
+  }
+  return out;
+}
+function compareVersions(a, b) {
+  const parts = (v) => {
+    const [core = "", pre = ""] = v.split("-", 2);
+    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+  };
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.nums.length, right.nums.length); i++) {
+    const diff = (left.nums[i] ?? 0) - (right.nums[i] ?? 0);
+    if (diff) return diff < 0 ? -1 : 1;
+  }
+  if (left.pre === right.pre) return 0;
+  if (!left.pre) return 1;
+  if (!right.pre) return -1;
+  return left.pre < right.pre ? -1 : 1;
+}
+function satisfies(installed, min) {
+  return compareVersions(installed, min) >= 0;
+}
+function unmetRequirements(requires, installedVersions) {
+  const unmet = [];
+  for (const requirement of parseRequires(requires)) {
+    const installed = installedVersions[requirement.name];
+    if (installed === void 0) {
+      unmet.push({ ...requirement, installed: null });
+    } else if (!satisfies(installed, requirement.min)) {
+      unmet.push({ ...requirement, installed });
+    }
+  }
+  return unmet;
+}
+function describeUnmet(slug, unmet) {
+  const detail = unmet.map((u) => `${u.name}@${u.min}${u.installed ? ` (you have ${u.installed})` : " (not installed here)"}`).join(", ");
+  return `note: runbook "${slug}" expects ${detail} \u2014 some steps may name commands your version does not have.`;
+}
+
+// src/runbook-actions.ts
 var PLATFORM_SCOPE = "$platform";
 async function call(ctx, method, path, body) {
   const res = await ctx.doFetch(`${ctx.platformUrl.replace(/\/$/, "")}/registry/pm${path}`, {
@@ -7856,19 +7909,23 @@ async function runbookList(ctx, all, query) {
 async function runbookGet(ctx, slug) {
   const runbook = await bySlug(ctx, slug);
   if (ctx.json) return ctx.out.log(JSON.stringify(runbook, null, 2));
+  const unmet = unmetRequirements(runbook.requires, { "@odla-ai/cli": cliVersion() });
+  if (unmet.length) ctx.out.error(describeUnmet(slug, unmet));
   ctx.out.log(runbook.body);
 }
-async function runbookNew(ctx, slug, title, body, summary) {
+async function runbookNew(ctx, slug, title, body, summary, requires) {
   const created = await call(ctx, "POST", "/runbook", {
     appId: ctx.appId,
-    input: { slug, title, body, ...summary ? { summary } : {} }
+    input: { slug, title, body, ...summary ? { summary } : {}, ...requires ? { requires } : {} }
   });
   ctx.out.log(ctx.json ? JSON.stringify(created, null, 2) : `created ${slug} (${created.id})`);
 }
-async function runbookEdit(ctx, slug, body, note) {
+async function runbookEdit(ctx, slug, body, note, requires) {
   const runbook = await bySlug(ctx, slug);
   const result = await call(ctx, "PATCH", `/runbook/${encodeURIComponent(runbook.id)}`, {
-    patch: { body, ...note ? { note } : {} }
+    // An empty --requires clears the declaration; omitting the flag leaves
+    // whatever is there, so an ordinary body edit never drops it.
+    patch: { body, ...note ? { note } : {}, ...requires === void 0 ? {} : { requires: requires || null } }
   });
   if (ctx.json) return ctx.out.log(JSON.stringify(result, null, 2));
   ctx.out.log(`${slug} \u2192 v${result.record?.version ?? runbook.version + 1}`);
@@ -8275,6 +8332,170 @@ 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;
+  const found = [];
+  for (const match of body.matchAll(re)) {
+    if (!match[1]) continue;
+    const words2 = match[2].trim().split(/[^\S\n]+/);
+    if (words2.length) found.push(words2);
+  }
+  return found;
+}
+function lintRunbook(runbook, installed) {
+  const findings = [];
+  const at = { slug: runbook.slug, appId: runbook.appId };
+  const declared = parseRequires(runbook.requires);
+  const seen = /* @__PURE__ */ new Set();
+  for (const words2 of invocationsIn(runbook.body)) {
+    const problem = validateInvocation(words2);
+    if (!problem) continue;
+    const key = `${problem.validPrefix}|${problem.word}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    findings.push({
+      ...at,
+      kind: declared.length ? "command" : "undeclared",
+      detail: declared.length ? `\`odla-ai ${words2.join(" ")}\`: ${describeProblem(problem)}` : `\`odla-ai ${words2.join(" ")}\`: ${describeProblem(problem)}. If a newer package added it, declare that with requires.`
+    });
+  }
+  const unmet = unmetRequirements(runbook.requires, installed);
+  if (unmet.length) findings.push({ ...at, kind: "requires", detail: describeUnmet(runbook.slug, unmet) });
+  return findings;
+}
+async function runbookLint(ctx, all) {
+  const params = new URLSearchParams();
+  if (!all) params.set("app", ctx.appId);
+  const page = await call(ctx, "GET", `/runbook${params.size ? `?${params}` : ""}`);
+  const installed = { "@odla-ai/cli": cliVersion() };
+  const findings = page.records.flatMap((runbook) => lintRunbook(runbook, installed));
+  if (ctx.json) return ctx.out.log(JSON.stringify({ checked: page.records.length, findings }, null, 2));
+  if (!page.records.length) return ctx.out.log("(no runbooks in scope)");
+  if (!findings.length) {
+    return ctx.out.log(
+      `${page.records.length} runbook${page.records.length === 1 ? "" : "s"} checked; every command they name is real for @odla-ai/cli ${cliVersion()}.`
+    );
+  }
+  ctx.out.log(`${findings.length} finding${findings.length === 1 ? "" : "s"} across ${page.records.length} runbooks:`);
+  for (const finding of findings) {
+    const scope = finding.appId === PLATFORM_SCOPE ? "" : ` --app ${finding.appId}`;
+    ctx.out.log("");
+    ctx.out.log(`${finding.slug} [${finding.kind}]`);
+    ctx.out.log(`  ${finding.detail}`);
+    ctx.out.log(`  odla-ai runbook get ${finding.slug}${scope}`);
+  }
+}
+
 // src/runbook-search-command.ts
 async function runbookSearch(ctx, query, all, limit) {
   const params = new URLSearchParams({ q: query });
@@ -8467,14 +8688,15 @@ var ALLOWED2 = [
   "visibility",
   "dry-run",
   "limit",
-  "base"
+  "base",
+  "requires"
 ];
 function requireSlug(slug, action) {
   if (!slug) throw new Error(`"runbook ${action}" needs a slug, e.g. "odla-ai runbook ${action} release"`);
   return slug;
 }
 var WRITES = /* @__PURE__ */ new Set(["new", "edit", "publish", "archive", "visibility", "revert", "rm", "import"]);
-var CONFIG_FREE = /* @__PURE__ */ new Set(["list", "search", "ask", "get", "cat", "history", "impact"]);
+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))) {
@@ -8556,6 +8778,8 @@ async function runbookCommand(parsed, deps = {}) {
       if (!question) throw new Error('"runbook ask" needs a question, e.g. odla-ai runbook ask "how do I roll back a publish?"');
       return runbookAsk(ctx, question, parsed.options.all === true);
     }
+    case "lint":
+      return runbookLint(ctx, parsed.options.all === true);
     case "impact":
       return runbookImpact(
         ctx,
@@ -8586,7 +8810,8 @@ async function runbookCommand(parsed, deps = {}) {
         name,
         stringOpt(parsed.options.title) ?? name,
         readBody(stringOpt(parsed.options.file), stringOpt(parsed.options.body)),
-        stringOpt(parsed.options.summary)
+        stringOpt(parsed.options.summary),
+        stringOpt(parsed.options.requires)
       );
     }
     case "edit": {
@@ -8595,7 +8820,13 @@ async function runbookCommand(parsed, deps = {}) {
       const inline = stringOpt(parsed.options.body);
       const body = file === void 0 && inline === void 0 ? await editRunbook(ctx, name) : readBody(file, inline);
       if (body === null) return ctx.out.log(`${name} unchanged; nothing written`);
-      return runbookEdit(ctx, name, body, stringOpt(parsed.options.note));
+      return runbookEdit(
+        ctx,
+        name,
+        body,
+        stringOpt(parsed.options.note),
+        parsed.options.requires === void 0 ? void 0 : stringOpt(parsed.options.requires) ?? ""
+      );
     }
     case "import": {
       const dir = parsed.positionals[2];
@@ -8624,9 +8855,7 @@ async function runbookCommand(parsed, deps = {}) {
     case "rm":
       return runbookRemove(ctx, requireSlug(slug, "rm"));
     default:
-      throw new Error(
-        `unknown runbook action "${action}". Try ask, search, impact, list, get, new, edit, comment, import, visibility, publish, archive, history, revert, rm.`
-      );
+      throw new Error(`unknown runbook action "${action}". Try ${acceptedAfter(["runbook"]).join(", ")}.`);
   }
 }