@odla-ai/cli 0.18.0 → 0.20.0

package/dist/index.cjs

@@ -35,8 +35,10 @@ __export(index_exports, {
   CAPABILITIES: () => CAPABILITIES,
   CODE_BUILD_RECIPES: () => CODE_BUILD_RECIPES,
   CODE_PI_IMAGE: () => CODE_PI_IMAGE,
+  COMMAND_SURFACE: () => COMMAND_SURFACE,
   GOOGLE_CALENDAR_EVENTS_SCOPE: () => GOOGLE_CALENDAR_EVENTS_SCOPE,
   SYSTEM_AI_PURPOSES: () => SYSTEM_AI_PURPOSES,
+  acceptedAfter: () => acceptedAfter,
   adminAi: () => adminAi,
   calendarBookingPageUrl: () => calendarBookingPageUrl,
   calendarCalendars: () => calendarCalendars,
@@ -46,6 +48,7 @@ __export(index_exports, {
   calendarStatus: () => calendarStatus,
   codeConnect: () => codeConnect,
   connectGitHubSecuritySource: () => connectGitHubSecuritySource,
+  describeProblem: () => describeProblem,
   disconnectGitHubSecuritySource: () => disconnectGitHubSecuritySource,
   doctor: () => doctor,
   exitCodeFor: () => exitCodeFor,
@@ -73,7 +76,9 @@ __export(index_exports, {
   secretsSet: () => secretsSet,
   secretsSetClerkKey: () => secretsSetClerkKey,
   smoke: () => smoke,
-  startHostedSecurityJob: () => startHostedSecurityJob
+  startHostedSecurityJob: () => startHostedSecurityJob,
+  surfacePaths: () => surfacePaths,
+  validateInvocation: () => validateInvocation
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -6489,11 +6494,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>]
@@ -6535,7 +6541,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
@@ -7856,6 +7865,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}`, {
@@ -7910,19 +7968,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}`);
@@ -8329,6 +8391,179 @@ 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(", ")}`;
+}
+function surfacePaths(node = COMMAND_SURFACE, prefix = []) {
+  const paths = [];
+  for (const [word, child] of Object.entries(node)) {
+    const path = [...prefix, word];
+    paths.push(path);
+    paths.push(...surfacePaths(child, path));
+  }
+  return paths;
+}
+
+// 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 });
@@ -8521,14 +8756,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))) {
@@ -8610,6 +8846,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,
@@ -8640,7 +8878,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": {
@@ -8649,7 +8888,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];
@@ -8678,9 +8923,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(", ")}.`);
   }
 }
 
@@ -9505,8 +9748,10 @@ async function calendarCommand(parsed, dependencies) {
   CAPABILITIES,
   CODE_BUILD_RECIPES,
   CODE_PI_IMAGE,
+  COMMAND_SURFACE,
   GOOGLE_CALENDAR_EVENTS_SCOPE,
   SYSTEM_AI_PURPOSES,
+  acceptedAfter,
   adminAi,
   calendarBookingPageUrl,
   calendarCalendars,
@@ -9516,6 +9761,7 @@ async function calendarCommand(parsed, dependencies) {
   calendarStatus,
   codeConnect,
   connectGitHubSecuritySource,
+  describeProblem,
   disconnectGitHubSecuritySource,
   doctor,
   exitCodeFor,
@@ -9543,6 +9789,8 @@ async function calendarCommand(parsed, dependencies) {
   secretsSet,
   secretsSetClerkKey,
   smoke,
-  startHostedSecurityJob
+  startHostedSecurityJob,
+  surfacePaths,
+  validateInvocation
 });
 //# sourceMappingURL=index.cjs.map