@elmundi/ship-cli 0.8.1 → 0.12.0

package/lib/commands/feedback.mjs

@@ -0,0 +1,355 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { spawn } from "node:child_process";
+import {
+  findShipRoot,
+  readConfig,
+} from "../config/io.mjs";
+import {
+  draftsDir,
+  createDraft,
+  listDrafts,
+  readDraft,
+  removeDraft,
+  moveDraftToSent,
+} from "../feedback/drafts.mjs";
+import { postFeedback } from "../http.mjs";
+import { appendEvent } from "../telemetry/outbox.mjs";
+
+const ALLOWED_KINDS = ["pattern", "tool", "collection", "doc"];
+
+function parseArgs(rest) {
+  const out = {
+    cwd: process.cwd(),
+    yes: false,
+    kind: null,
+    id: null,
+    version: null,
+    title: null,
+    summary: null,
+    recommendation: null,
+    positional: [],
+  };
+  const copy = [...rest];
+  const strFlag = (name, key) => {
+    if (copy[0] === name && copy[1] !== undefined) {
+      copy.shift();
+      out[key] = String(copy.shift());
+      return true;
+    }
+    const p = `${name}=`;
+    if (copy[0] && copy[0].startsWith(p)) {
+      out[key] = copy[0].slice(p.length);
+      copy.shift();
+      return true;
+    }
+    return false;
+  };
+  while (copy.length) {
+    if (copy[0] === "--cwd" && copy[1]) {
+      copy.shift();
+      out.cwd = String(copy.shift());
+      continue;
+    }
+    if (copy[0] && copy[0].startsWith("--cwd=")) {
+      out.cwd = copy.shift().slice("--cwd=".length);
+      continue;
+    }
+    if (copy[0] === "--yes" || copy[0] === "-y") {
+      out.yes = true;
+      copy.shift();
+      continue;
+    }
+    if (strFlag("--kind", "kind")) continue;
+    if (strFlag("--id", "id")) continue;
+    if (strFlag("--version", "version")) continue;
+    if (strFlag("--title", "title")) continue;
+    if (strFlag("--summary", "summary")) continue;
+    if (strFlag("--recommendation", "recommendation")) continue;
+    out.positional.push(copy.shift());
+  }
+  return out;
+}
+
+function requireShipRoot(cwd) {
+  const root = findShipRoot(cwd);
+  if (!root) {
+    console.error(".ship/ not found. Run 'shipctl config init' first.");
+    process.exit(10);
+  }
+  return root;
+}
+
+async function promptLine(msg) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return await new Promise((resolve) => rl.question(msg, resolve));
+  } finally {
+    rl.close();
+  }
+}
+
+function resolveBaseUrl(ctx, config) {
+  return (
+    ctx?.baseUrl ||
+    process.env.SHIP_API_BASE ||
+    config?.api?.base_url ||
+    "https://ship.elmundi.com"
+  ).replace(/\/$/, "");
+}
+
+async function cmdDraft(root, args) {
+  if (!args.kind || !ALLOWED_KINDS.includes(args.kind)) {
+    console.error(`--kind is required and must be one of: ${ALLOWED_KINDS.join(", ")}`);
+    process.exit(1);
+  }
+  if (!args.id) {
+    console.error("--id is required");
+    process.exit(1);
+  }
+
+  let title = args.title;
+  let summary = args.summary;
+
+  if ((!title || !summary) && process.stdin.isTTY) {
+    if (!title) title = (await promptLine("title: ")).trim();
+    if (!summary) summary = (await promptLine("summary: ")).trim();
+  }
+
+  if (!title || !summary) {
+    console.error("--title and --summary are required (interactive prompts unavailable).");
+    process.exit(1);
+  }
+
+  const { config } = readConfig(root);
+  const fp = createDraft(root, {
+    kind: args.kind,
+    id: args.id,
+    version: args.version,
+    title,
+    summary,
+    recommendation: args.recommendation,
+    stack: config.stack || {},
+  });
+  console.log(fp);
+}
+
+function cmdList(root) {
+  const drafts = listDrafts(root);
+  if (drafts.length === 0) {
+    console.log("(no feedback drafts)");
+    return;
+  }
+  for (const fp of drafts) {
+    try {
+      const { meta } = readDraft(fp);
+      const sent = fp.includes(`${path.sep}sent${path.sep}`) ? " [sent]" : "";
+      const base = path.basename(fp);
+      const ts = (base.match(/^([0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{2})/) || [])[1] || "-";
+      const kind = meta.kind || "-";
+      const id = meta.id || "-";
+      const version = meta.version || "-";
+      const title = meta.title || "(untitled)";
+      console.log(`${ts} ${kind}/${id}@${version} — ${title}${sent}`);
+    } catch (e) {
+      console.log(`${fp} (invalid: ${e.message})`);
+    }
+  }
+}
+
+function cmdShow(args) {
+  const file = args.positional[1];
+  if (!file) {
+    console.error("usage: shipctl feedback show <draft-file>");
+    process.exit(1);
+  }
+  const resolved = path.resolve(file);
+  if (!fs.existsSync(resolved)) {
+    console.error(`not found: ${resolved}`);
+    process.exit(1);
+  }
+  console.log(fs.readFileSync(resolved, "utf8"));
+}
+
+function cmdEdit(args) {
+  const file = args.positional[1];
+  if (!file) {
+    console.error("usage: shipctl feedback edit <draft-file>");
+    process.exit(1);
+  }
+  const resolved = path.resolve(file);
+  if (!fs.existsSync(resolved)) {
+    console.error(`not found: ${resolved}`);
+    process.exit(1);
+  }
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) {
+    console.log(resolved);
+    console.error("(hint: set $EDITOR to open drafts automatically)");
+    return;
+  }
+  const [cmd, ...cmdArgs] = editor.split(/\s+/);
+  const child = spawn(cmd, [...cmdArgs, resolved], { stdio: "inherit" });
+  child.on("exit", (code) => {
+    if (code !== 0) process.exit(code || 1);
+  });
+}
+
+async function cmdSubmit(ctx, root, args) {
+  const file = args.positional[1];
+  if (!file) {
+    console.error("usage: shipctl feedback submit <draft-file>");
+    process.exit(1);
+  }
+  const resolved = path.resolve(file);
+  if (!fs.existsSync(resolved)) {
+    console.error(`not found: ${resolved}`);
+    process.exit(1);
+  }
+
+  const { meta, body } = readDraft(resolved);
+  const missing = [];
+  if (!meta.kind) missing.push("kind");
+  if (!meta.id) missing.push("id");
+  if (!meta.title) missing.push("title");
+  // Summary lives in body (after '**Summary**:'); derive it for validation.
+  const summaryMatch = body.match(/\*\*Summary\*\*:\s*([^\n]+)/);
+  const summary = summaryMatch ? summaryMatch[1].trim() : "";
+  if (!summary) missing.push("summary");
+  if (missing.length) {
+    console.error(`missing required fields: ${missing.join(", ")}`);
+    process.exit(1);
+  }
+
+  if (!args.yes && process.stdin.isTTY) {
+    const ok = (await promptLine(`submit ${path.basename(resolved)}? [y/N] `)).trim();
+    if (!/^y(es)?$/i.test(ok)) {
+      console.error("aborted.");
+      process.exit(1);
+    }
+  }
+
+  const { config } = readConfig(root);
+  const baseUrl = resolveBaseUrl(ctx, config);
+
+  const stack = config.stack || {};
+  const stackStr = `tracker=${stack.tracker || "-"}, ci=${stack.ci || "-"}, agents=${
+    Array.isArray(stack.agents) ? stack.agents.join("+") || "-" : "-"
+  }, preset=${stack.preset || "-"}`;
+
+  const recommendationMatch = body.match(/\*\*Recommendation\*\*:\s*([^\n]+)/);
+  const recommendation = recommendationMatch ? recommendationMatch[1].trim() : "";
+  const recommendations = recommendation ? [recommendation] : [];
+
+  const payload = {
+    title: meta.title,
+    summary,
+    recommendations,
+    source_context: stackStr,
+    artifact: {
+      kind: meta.kind,
+      id: meta.id,
+      version: meta.version || undefined,
+    },
+  };
+
+  let data;
+  try {
+    data = await postFeedback(baseUrl, payload);
+  } catch (e) {
+    console.error(e.message || String(e));
+    process.exit(20);
+  }
+
+  const issueUrl = data?.issue_url || "(no issue_url in response)";
+  console.log(issueUrl);
+  if (data?.deduplicated) console.log("(deduplicated: comment added to existing issue)");
+
+  const sentPath = moveDraftToSent(root, resolved);
+  console.log(`moved: ${sentPath}`);
+
+  if (
+    config.telemetry?.share === true &&
+    config.telemetry?.scope?.improvement_drafts === true
+  ) {
+    try {
+      appendEvent(root, {
+        type: "feedback.submit",
+        anonymous_id: config.telemetry.anonymous_id,
+        payload: {
+          artifact: {
+            kind: meta.kind,
+            id: meta.id,
+            version: meta.version || null,
+          },
+          summary,
+          suggestion: recommendation || null,
+          stack: {
+            tracker: stack.tracker || null,
+            ci: stack.ci || null,
+            agents: stack.agents || [],
+            preset: stack.preset || null,
+          },
+        },
+      });
+    } catch (e) {
+      if (process.env.SHIP_DEBUG === "1") {
+        console.error(`[ship:feedback] failed to append telemetry: ${e.message}`);
+      }
+    }
+  }
+}
+
+function cmdRemove(args) {
+  const file = args.positional[1];
+  if (!file) {
+    console.error("usage: shipctl feedback remove <draft-file>");
+    process.exit(1);
+  }
+  const resolved = path.resolve(file);
+  if (!fs.existsSync(resolved)) {
+    console.error(`not found: ${resolved}`);
+    process.exit(1);
+  }
+  removeDraft(resolved);
+  console.log(`removed: ${resolved}`);
+}
+
+export async function feedbackCommand(ctx, rest) {
+  const args = parseArgs(rest);
+  const sub = args.positional[0];
+  const root = requireShipRoot(args.cwd);
+  // ensure drafts dir exists lazily when commands need it
+  if (sub === "list" || sub === "draft") fs.mkdirSync(draftsDir(root), { recursive: true });
+
+  switch (sub) {
+    case "draft":
+      await cmdDraft(root, args);
+      return;
+    case "list":
+      cmdList(root);
+      return;
+    case "show":
+      cmdShow(args);
+      return;
+    case "edit":
+      cmdEdit(args);
+      return;
+    case "submit":
+      await cmdSubmit(ctx, root, args);
+      return;
+    case "remove":
+      cmdRemove(args);
+      return;
+    default:
+      console.error(
+        "usage: shipctl feedback <draft|list|show|edit|submit|remove> [...]\n" +
+          "  draft  --kind <k> --id <id> [--version <v>] --title '...' --summary '...' [--recommendation '...']\n" +
+          "  list\n" +
+          "  show|edit|remove <draft-file>\n" +
+          "  submit <draft-file> [--yes]",
+      );
+      process.exit(2);
+  }
+}

package/lib/commands/help.mjs

@@ -1,39 +1,174 @@
 export function printHelp() {
-  console.log(`Ship CLI — methodology on ship.elmundi.com (or SHIP_API_BASE) + init.
+  console.log(`shipctl — adopt Ship in a repo, sync the catalog, run lanes, report Runs.
 
-ONE FLOW
-  1) ship search <query>     — vector search (POST /search) over docs + prompts + README
-  2) ship docs fetch <path>  — full markdown file by repo-relative path (POST /fetch { path })
-     ship pattern|tool|workflow|collection fetch <id> — catalog entry body (POST /fetch { kind, id })
-  3) ship docs feedback …   — improvement / retro note (POST /feedback)
+Bootstrap a new or existing repo (init / new / doctor), pull the
+methodology catalog into .ship/cache (sync), execute one-shot lanes or
+emit prompts for the workspace runner (run / lanes / kickoff /
+callback). Talks to the methodology + orchestration APIs over HTTPS.
+
+VOCABULARY
+  lanes:   (.ship/config.yml)  → operator console: Automations
+  pattern: (artifact kind)     → operator console: Plays
+  pipeline_runs (DB / API)     → operator console: Runs
+  attention surface            → operator console: Inbox
+
+The protocol-stable terms (lanes:, pattern:, pipeline_runs) stay
+literal in YAML, CLI flags, and HTTP. Operator-facing prose uses the
+console nouns.
+
+GLOBAL FLAGS
+  --base-url URL   Methodology API (default: SHIP_API_BASE or
+                   https://ship.elmundi.com/api/methodology)
+  --json           Machine-readable JSON output where supported
+  --version, -v    Print shipctl version and exit
+  --help, -h       Print this help
 
 COMMANDS
-  ship help
-  ship search <query> [--top-k N]
 
-  ship docs fetch <repo-relative-path>
-  ship docs feedback --title "..." --summary "..." [--recommendation "…"]... [--source-context "…"]
+  Setup
+    shipctl init [--yes] [--force] [--dry-run] [--json] [--cwd <dir>]
+                 [--agents <csv>]
+                 [--tracker <name>] [--ci <name>] [--preset <name>]
+                 [--language <name>] [--channel stable|edge]
+                 [--copy-rules] [--copy-playbook] [--bootstrap]
+                 [--telemetry on|off|ask]
+                                       — bootstrap .ship/, fetch artifacts, install
+                                         agent rules in an existing repo.
+    shipctl new <name> [--preset ...] [--tracker ...] [--ci ...] [--agents ...]
+                       [--here] [--yes]
+                                       — bootstrap a fresh repo: git init + README +
+                                         .ship/config.yml.
+    shipctl doctor [--json] [--cwd <dir>] [--write-inventory] [--no-network]
+                                       — inspect the repo, propose a stack, optionally
+                                         write .ship/inventory.json for
+                                         'shipctl init --bootstrap'.
+    shipctl config init|get|set|validate|show|path
+                                       — .ship/config.yml management.
 
-  ship pattern list | ship pattern show <id> | ship pattern fetch <id> | ship pattern search <query> [--top-k N]
-  ship tool … | ship workflow … | ship collection …   (same subcommands; plural aliases: patterns, tools, …)
+  Catalog
+    shipctl search <query> [--top-k N]
+                                       — vector search over docs + prompts (POST /search).
+    shipctl docs fetch <repo-relative-path>
+    shipctl docs feedback --title "..." --summary "..." [--recommendation "..."]...
+                          [--source-context "..."]
+                                       — fetch markdown bodies; submit improvement /
+                                         retro notes (POST /feedback).
+    shipctl pattern list | shipctl pattern show <id> | shipctl pattern fetch <id>
+                                     | shipctl pattern search <query> [--top-k N]
+                                       — versioned artifact bodies (POST /fetch
+                                         { kind, id, version? }). 'pattern' is the
+                                         protocol-stable artifact kind; in the operator
+                                         console it shows up as a Play.
+    shipctl tool …       | shipctl collection …
+                                       — same subcommands; plural aliases:
+                                         patterns, tools, collections.
+    shipctl sync [--check-only] [--only <kind:id>]... [--channel <c>]
+                 [--force-unpin] [--dry-run] [--lock] [--json] [--cwd <dir>]
+                                       — fetch artifacts into .ship/cache. With --lock,
+                                         also writes .ship/shipctl.lock.json covering
+                                         every pattern the declared lanes depend on.
 
-  ship init [--yes] [--force] [--dry-run] [--only <id>] [--cwd <dir>]
+  Run
+    shipctl trigger --event schedule --repo <id|owner/name> [--workspace <id>] [--json]
+                                       — ask Ship which configured lanes are
+                                         due for the current GitHub trigger.
+    shipctl run --lane <id> [--pattern <id>] [--fanout matrix|sequential|concurrent]
+                [--trigger event|schedule|manual|once]
+                [--dry-run] [--offline] [--json] [--cwd <dir>]
+                [--ship-run-id <uuid>] [--ship-callback-url <url>] [--ship-run-token <jwt>]
+                                       — one-shot dispatch entry point. 'kind: once'
+                                         lanes execute fully here; 'kind: lane / event /
+                                         schedule' lanes are queued for the workspace
+                                         runner via .github/workflows/run-agent.yml.
+                                         Reports its terminal status via the callback URL
+                                         Ship injected into the workflow.
+    shipctl lanes install [--only <csv>] [--ref <git-ref>] [--owner <gh>] [--repo <name>]
+                          [--shipctl-version <v>] [--dry-run] [--force] [--json] [--cwd <dir>]
+    shipctl lanes list   [--json] [--cwd <dir>]
+    shipctl lanes remove [--only <csv>] [--dry-run] [--json] [--cwd <dir>]
+                                       — generate / inspect / delete the
+                                         .github/workflows/ship-<lane>.yml thin wrappers
+                                         that delegate to the reusable run-agent.yml.
+    shipctl kickoff [--pattern <id>] [--version <v>] [--raw] [--json] [--cwd <dir>]
+                                       — print a pattern body for piping into the
+                                         customer's agent in CI.
+    shipctl callback --status <ok|fail|cancelled> [--summary "..."] [--metric k=v]...
+                     [--outcome-text "..."] [--findings-count N] [--severity high=N]...
+                     [--artifact pr:"..."]... [--escalation clarification:"..."]...
+                                       — report a Run's terminal status (and
+                                         RunSummary outcome) back to Ship so it can
+                                         render the outcome row and route any
+                                         escalations into the Inbox.
 
-GLOBAL FLAGS
-  --base-url URL   Methodology API (default: SHIP_API_BASE or https://ship.elmundi.com/api/methodology)
-  --json           Machine-readable JSON
+  Knowledge
+    shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>] [--only <csv>] [--json]
+                                       — compatibility: open a PR that seeds
+                                         .ship/knowledge starter docs.
+    shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]
+                                       — read Ship-owned bucket articles and
+                                         source sync state.
+    shipctl knowledge bootstrap [--workspace <id>] [--repo <id|owner/name>] [--json]
+                                       — post-merge action entry point: analyze
+                                         repo and open generated knowledge PR.
+    shipctl knowledge refresh-intel [--workspace <id>] [--repo <id|owner/name>] [--json]
+                                       — refresh the generated repository-context
+                                         bucket for an activated repo.
+                                         Reads SHIP_API_TOKEN.
+
+  Telemetry & feedback
+    shipctl telemetry status|on|off|show-id|reset-id|flush|export|delete-my-data|buffer
+                                       — opt-in anonymous usage (RFC-0003); default OFF.
+                                         '--scope artifact_usage,improvement_drafts,errors'
+                                         on 'on'; '--dry-run' on 'flush';
+                                         '--out <file>' on 'export'.
+    shipctl feedback draft|list|show|edit|submit|remove
+                                       — local markdown drafts; submit creates a
+                                         GitHub issue via POST /feedback and moves the
+                                         draft to sent/.
+
+  Misc
+    shipctl verify [--no-network] [--check <id,...>] [--severity warn|error|info] [--json]
+                                       — post-adoption liveness checks
+                                         (local + config + network).
+    shipctl migrate [--dry-run] [--yes] [--json] [--cwd <dir>]
+                                       — upgrade .ship/config.yml from v1 to v2
+                                         (lanes-as-config).
+    shipctl bootstrap   (stub)
+    shipctl help                       — show this help.
 
 LOCAL TREE
-  pattern / tool / workflow / collection list|show|fetch read manifests from disk when cwd or SHIP_REPO
-  is inside the Ship monorepo (search always uses HTTP).
+  pattern / tool / collection list|show|fetch scan
+  artifacts/<plural>/<id>/ARTIFACT.md on disk when cwd or SHIP_REPO is inside
+  the Ship monorepo (search always uses HTTP).
 
 INIT FLAGS
-  --yes       Non-interactive apply (use --dry-run first)
-  --force     Replace existing injected blocks
-  --dry-run   Preview only
-  --only      cursor | agents-md | claude-md | codex | copilot
-  --cwd       Target repo root
+  --yes              Non-interactive apply (use --dry-run first)
+  --force            Replace existing rule blocks and overwrite generated files
+  --dry-run          Preview only
+  --json             Emit a JSON summary suitable for CI
+  --agents <csv>     Comma-separated agent ids. See list below.
+  --tracker <name>   Stack tracker: linear|jira|github-issues|azure-boards|clickup|spreadsheet|none
+  --ci <name>        Stack CI: gh-actions|gitlab-ci|buildkite|circleci|azure-pipelines|jenkins|manual
+  --preset <name>    Stack preset: web-app|api-backend|mobile-app|cli|monorepo|adoption-minimum
+  --language <name>  Stack language: ts|js|py|go|rust|java|kotlin|swift|dart|multi
+  --channel <name>   Override api.channel: stable|edge
+  --copy-rules       Install collection/agent-rules-<agent> files at their install_target
+  --copy-playbook    Fetch collection/adoption-playbook into .ship/cache/ (skipped on 404)
+  --bootstrap        Render CI/tracker scaffolding (mobile-app+gh-actions+linear skeletons today;
+                     other combos emit SHIP_BOOTSTRAP_PLAN.md)
+  --telemetry        on|off|ask — override the interactive telemetry prompt
+  --cwd              Target repo root
+
+SUPPORTED AGENTS
+  cursor, codex, claude, aider, cline, continue, windsurf, zed,
+  gemini, opencode, copilot, cursor-cloud, agents-md, claude-md
+
+REFERENCE
+  Artifacts protocol: RFC-0001 (POST /search, POST /fetch). Every consumed
+  artifact should be recorded in the PR as \`<kind>:<id>@<version>\`.
+  HTTP schemas: artifacts/tools/methodology-api/ARTIFACT.md in the Ship repo.
+  Operator IA (Plays / Automations / Runs / Inbox): RFC-0010.
 
-For HTTP schemas see documentation/tools/backend-api.md in the Ship repo.
+Package: @elmundi/ship-cli (binary: shipctl).
 `);
 }