@elmundi/ship-cli 0.8.1 → 0.11.2

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,114 @@
 export function printHelp() {
-  console.log(`Ship CLI — methodology on ship.elmundi.com (or SHIP_API_BASE) + init.
+  console.log(`Ship CLI — artifacts protocol on ship.elmundi.com (or SHIP_API_BASE) + init.
 
-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)
+ARTIFACTS PROTOCOL (RFC-0001)
+  1) shipctl search <query>          — vector search (POST /search) over docs + prompts
+  2) shipctl docs fetch <path>       — full markdown body by repo-relative path
+     shipctl pattern|tool|collection show|fetch <id>
+                                     — versioned artifact body (POST /fetch { kind, id, version? })
+  3) shipctl docs feedback …         — improvement / retro note (POST /feedback)
+
+Every consumed artifact should be recorded in the PR as \`<kind>:<id>@<version>\`.
 
 COMMANDS
-  ship help
-  ship search <query> [--top-k N]
+  shipctl help
+  shipctl search <query> [--top-k N]
+
+  shipctl docs fetch <repo-relative-path>
+  shipctl docs feedback --title "..." --summary "..." [--recommendation "…"]... [--source-context "…"]
+
+  shipctl pattern list | shipctl pattern show <id> | shipctl pattern fetch <id> | shipctl pattern search <query> [--top-k N]
+  shipctl tool … | shipctl collection …   (same subcommands; plural aliases: patterns, tools, …)
 
-  ship docs fetch <repo-relative-path>
-  ship docs feedback --title "..." --summary "..." [--recommendation "…"]... [--source-context "…"]
+  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]
 
-  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, …)
+  shipctl doctor [--json] [--cwd <dir>] [--write-inventory] [--no-network]
+                                     — inspect the repo, propose a stack, optionally write
+                                       .ship/inventory.json for 'shipctl init --bootstrap'.
 
-  ship init [--yes] [--force] [--dry-run] [--only <id>] [--cwd <dir>]
+  shipctl config init|get|set|validate|show|path     — .ship/config.yml management
+  shipctl sync [--check-only] [--only <kind:id>...] [--channel <c>] [--force-unpin]
+               [--dry-run] [--lock] [--json]
+                                     — fetch artifacts into .ship/cache. With --lock,
+                                       also writes .ship/shipctl.lock.json covering every
+                                       pattern the declared lanes depend on (Phase 4).
+
+  shipctl new <name> [--preset ...] [--tracker ...] [--ci ...] [--agents ...] [--here] [--yes]
+                                     — bootstrap a fresh repo: git init + README + .ship/config.yml
+  shipctl verify [--no-network] [--check <id,...>] [--severity warn|error|info] [--json]
+                                     — post-adoption liveness checks (local + config + network)
+  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/.
+  shipctl callback --status <ok|fail|cancelled> [--summary "..."] [--metric k=v]...
+                                     — report a pipeline run's terminal status to Ship.
+                                       Used inside workflow.yml 'if: always()' steps;
+                                       reads SHIP_RUN_TOKEN + SHIP_CALLBACK_URL from env.
+  shipctl kickoff [--pattern kickoff] [--version …] [--raw] [--json] [--cwd …]
+                                     — print the kickoff / workload pattern body for piping
+                                       into the customer's agent in CI (see artifacts/patterns/kickoff).
+  shipctl migrate [--dry-run] [--yes] [--json] [--cwd …]
+                                     — upgrade .ship/config.yml from v1 to v2 (lanes-as-config).
+  shipctl run --lane <id> [--trigger event|schedule|manual|once]
+              [--dry-run] [--offline] [--json] [--cwd …]
+              [--ship-run-id …] [--ship-callback-url …] [--ship-run-token …]
+                                     — RFC-0007 entry-point: resolve a lane from
+                                       .ship/config.yml, fetch its pattern, check idempotency,
+                                       emit the prompt, and report the callback.
+  shipctl lanes install [--only <csv>] [--ref <git-ref>] [--owner …] [--repo …]
+                        [--shipctl-version <v>] [--dry-run] [--force] [--json] [--cwd …]
+                                     — generate .github/workflows/ship-<lane>.yml thin
+                                       wrappers that delegate to the reusable run-agent.yml.
+  shipctl lanes list [--json] [--cwd …]
+                                     — print the lane map from .ship/config.yml.
+  shipctl lanes remove [--only <csv>] [--dry-run] [--json] [--cwd …]
+                                     — delete generated ship-<lane>.yml wrappers.
+  shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>] [--only <csv>] [--json]
+                                     — open a PR that seeds .ship/knowledge/*.md starter
+                                       buckets (code-style, ui-runbook). Reads SHIP_API_TOKEN.
+  shipctl bootstrap   (stub)
 
 GLOBAL FLAGS
   --base-url URL   Methodology API (default: SHIP_API_BASE or https://ship.elmundi.com/api/methodology)
   --json           Machine-readable JSON
 
 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
 
-For HTTP schemas see documentation/tools/backend-api.md in the Ship repo.
+For HTTP schemas see artifacts/tools/methodology-api/ARTIFACT.md in the Ship repo.
+Package: @elmundi/ship-cli (binary: shipctl).
 `);
 }