@elmundi/ship-cli 0.8.1 → 0.11.2

package/lib/commands/manifest-catalog.mjs

@@ -1,27 +1,20 @@
-import fs from "node:fs";
 import path from "node:path";
-import { apiGet, apiPost } from "../http.mjs";
+import { apiGet, apiPost, fetchArtifact } from "../http.mjs";
 import { resolveShipRepoRootForCatalog } from "../find-ship-root.mjs";
+import { findShipRoot } from "../config/io.mjs";
+import { writeCached, cachePath } from "../cache/store.mjs";
 import { searchCommand } from "./search.mjs";
+import { scanArtifacts, readArtifactFile, pluralFor } from "../artifacts/fs-index.mjs";
 
-/** @type {Record<string, { manifestRel: string; arrayKey: string; name: string; apiPath: string; fetchKind: string }>} */
+/** @type {Record<string, { arrayKey: string; name: string; apiPath: string; fetchKind: "tool"|"collection" }>} */
 const RESOURCES = {
   tool: {
-    manifestRel: "tools/manifest.json",
     arrayKey: "tools",
     name: "Tools",
     apiPath: "tools",
     fetchKind: "tool",
   },
-  workflow: {
-    manifestRel: "workflows/manifest.json",
-    arrayKey: "workflows",
-    name: "Workflows",
-    apiPath: "workflows",
-    fetchKind: "workflow",
-  },
   collection: {
-    manifestRel: "collections/manifest.json",
     arrayKey: "collections",
     name: "Collections",
     apiPath: "collections",
@@ -30,7 +23,7 @@ const RESOURCES = {
 };
 
 /**
- * @param {"tool"|"workflow"|"collection"} resource
+ * @param {"tool"|"collection"} resource
  * @param {{ baseUrl: string; json: boolean }} ctx
  * @param {string[]} args
  */
@@ -40,15 +33,20 @@ export async function resourceManifestCommand(resource, ctx, args) {
 
   const [sub, ...rest] = args;
   if (!sub || sub === "help") {
+    const plural = pluralFor(spec.fetchKind);
     console.log(`Usage:
   ship ${resource} list
   ship ${resource} show <id>
-  ship ${resource} fetch <id>
+  ship ${resource} fetch <id> [--version V] [--print]
   ship ${resource} search <query> [--top-k N]
 
-With a local Ship tree (cwd or SHIP_REPO): reads ${spec.manifestRel} on disk.
+With a local Ship tree (cwd or SHIP_REPO): scans artifacts/${plural}/<id>/ARTIFACT.md on disk.
 Otherwise: methodology API (GET /${spec.apiPath}, POST /fetch for fetch, POST /search for search).
 
+In a Ship workspace (.ship/config.yml), 'fetch' writes the artifact to
+.ship/cache/<kind>/<id>@<version>/ARTIFACT.md and prints a 'cached:' line. Pass
+--print to also echo the body on stdout.
+
 Plural alias: ship ${spec.apiPath} …
 
 Global flags: --base-url URL  --json`);
@@ -69,7 +67,29 @@ Global flags: --base-url URL  --json`);
 }
 
 /**
- * @param {"tool"|"workflow"|"collection"} resource
+ * Parse `fetch`-specific flags so the hosted catalog path can honour
+ * `--print`, `--version` and `--cwd` without polluting the global flag
+ * extractor. Unknown flags are silently preserved as positionals (no error),
+ * matching the rest of the manifest-catalog command.
+ * @param {string[]} rest
+ */
+function parseFetchFlags(rest) {
+  const out = { positional: /** @type {string[]} */ ([]), print: false, version: null, cwd: null };
+  const copy = [...rest];
+  while (copy.length) {
+    const a = copy.shift();
+    if (a === "--print") { out.print = true; continue; }
+    if (a === "--version" && copy.length) { out.version = copy.shift(); continue; }
+    if (a && a.startsWith("--version=")) { out.version = a.slice("--version=".length); continue; }
+    if (a === "--cwd" && copy.length) { out.cwd = copy.shift(); continue; }
+    if (a && a.startsWith("--cwd=")) { out.cwd = a.slice("--cwd=".length); continue; }
+    out.positional.push(a);
+  }
+  return out;
+}
+
+/**
+ * @param {"tool"|"collection"} resource
  */
 async function manifestFromHosted(resource, spec, ctx, sub, rest) {
   const base = ctx.baseUrl;
@@ -106,16 +126,67 @@ async function manifestFromHosted(resource, spec, ctx, sub, rest) {
     return;
   }
   if (sub === "fetch") {
-    const id = rest[0];
+    const flags = parseFetchFlags(rest);
+    const id = flags.positional[0];
     if (!id) {
       console.error("fetch: id required.");
       process.exit(1);
     }
-    const data = await apiPost(base, "/fetch", { kind: spec.fetchKind, id });
+
+    const shipRoot = findShipRoot(flags.cwd || process.cwd());
+    const wantCache = !!shipRoot;
+    const wantStdoutBody = flags.print || !wantCache || ctx.json;
+
+    if (wantCache) {
+      const { content, meta } = await fetchArtifact(
+        base,
+        spec.fetchKind,
+        id,
+        flags.version || undefined,
+      );
+      const version = meta.version || flags.version || "0.0.0";
+      const writeRes = writeCached(shipRoot, spec.fetchKind, id, version, content, {
+        content_sha256: meta.content_sha256,
+        updated_at: meta.updated_at,
+        channel: meta.channel,
+        version,
+        source_url: meta.source_url,
+      });
+      const rel = path.relative(shipRoot, writeRes.bodyPath) || cachePath(shipRoot, spec.fetchKind, id, version);
+      const relDisplay = path.isAbsolute(rel) ? writeRes.bodyPath : rel;
+      if (ctx.json) {
+        console.log(
+          JSON.stringify(
+            {
+              kind: spec.fetchKind,
+              id,
+              version,
+              content_sha256: meta.content_sha256,
+              cached_path: relDisplay,
+              content: wantStdoutBody ? content : undefined,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        console.log(`cached: ${spec.fetchKind}/${id}@${version} \u2192 ${relDisplay}`);
+        if (wantStdoutBody) {
+          console.log(`# ${id}@${version}\n`);
+          console.log(content);
+        }
+      }
+      return;
+    }
+
+    const data = await apiPost(base, "/fetch", { kind: spec.fetchKind, id, ...(flags.version ? { version: flags.version } : {}) });
     if (ctx.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
-      console.log(`# ${data.title} (${data.id})\n`);
+      console.error(
+        `note: not in a Ship workspace (no .ship/config.yml found); printing body only. Run 'shipctl config init' to enable caching.`,
+      );
+      console.log(`# ${data.title || data.id} (${data.id})\n`);
       console.log(data.content);
     }
     return;
@@ -125,22 +196,21 @@ async function manifestFromHosted(resource, spec, ctx, sub, rest) {
 }
 
 /**
- * @param {"tool"|"workflow"|"collection"} resource
+ * @param {"tool"|"collection"} resource
  */
 async function manifestFromDisk(resource, root, spec, ctx, sub, rest) {
-  const manifestPath = path.join(root, spec.manifestRel);
-  const raw = fs.readFileSync(manifestPath, "utf8");
-  /** @type {Record<string, unknown>} */
-  const data = JSON.parse(raw);
-  const entries = /** @type {Array<{ id: string; title: string; summary?: string; path: string; tags?: string[] }>} */ (
-    data[spec.arrayKey] || []
-  );
+  const entries = scanArtifacts(root, spec.fetchKind);
 
   if (sub === "list") {
     if (ctx.json) {
-      console.log(JSON.stringify(data, null, 2));
+      const payload = {
+        description: spec.name,
+        version: 1,
+        [spec.arrayKey]: entries,
+      };
+      console.log(JSON.stringify(payload, null, 2));
     } else {
-      console.log(`${data.description || spec.name}\n`);
+      console.log(`${spec.name}\n`);
       for (const p of entries) {
         console.log(`- ${p.id}`);
         console.log(`  ${p.title}`);
@@ -161,18 +231,12 @@ async function manifestFromDisk(resource, root, spec, ctx, sub, rest) {
       console.error(`Unknown id: ${id}`);
       process.exit(1);
     }
-    const abs = path.resolve(root, entry.path);
-    const rootNorm = root.endsWith(path.sep) ? root.slice(0, -1) : root;
-    const absNorm = abs.endsWith(path.sep) ? abs.slice(0, -1) : abs;
-    if (absNorm !== rootNorm && !abs.startsWith(root + path.sep)) {
-      console.error("Manifest path escapes repository root.");
-      process.exit(1);
-    }
-    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    const file = readArtifactFile(root, spec.fetchKind, id);
+    if (!file) {
       console.error(`Missing file: ${entry.path}`);
       process.exit(1);
     }
-    const content = fs.readFileSync(abs, "utf8");
+    const content = file.content;
     if (ctx.json) {
       console.log(JSON.stringify({ ...entry, content }, null, 2));
     } else {

package/lib/commands/migrate.mjs

@@ -0,0 +1,204 @@
+/**
+ * `shipctl migrate` — upgrade `.ship/config.yml` from v1 to v2 (RFC-0007).
+ *
+ * The command is conservative:
+ *   - Writes `.ship/config.yml.bak` before touching anything.
+ *   - Refuses to overwrite without `--yes` unless `--dry-run` is set.
+ *   - Emits a machine-readable summary under `--json` so adopters can
+ *     wire it into their own migration runbooks.
+ *
+ * The actual migration rules live in `cli/lib/config/migrate.mjs`; this
+ * command is the I/O and UX layer.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { readConfig, writeConfig } from "../config/io.mjs";
+import { validateConfig } from "../config/schema.mjs";
+import { migrateV1ToV2 } from "../config/migrate.mjs";
+
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+const EXIT_NOOP = 0;
+const EXIT_VALIDATION = 1;
+
+function printHelp() {
+  console.log(`shipctl migrate — upgrade .ship/config.yml to the current schema.
+
+USAGE
+  shipctl migrate [--dry-run] [--yes] [--json] [--cwd <dir>]
+
+FLAGS
+  --dry-run   Print the proposed new config without writing to disk.
+  --yes       Skip the interactive confirmation and overwrite in place
+              (a backup is always written to .ship/config.yml.bak first).
+  --json      Emit a structured summary (path, backup, warnings, stubs).
+  --cwd <dir> Repo root (default: search upward for .ship/config.yml).
+  --help      Show this help.
+
+EXIT
+  0  migration applied (or already at the latest schema)
+  1  resulting config failed validation
+  2  argument / IO error
+`);
+}
+
+/**
+ * @param {{json?: boolean, yes?: boolean, dryRun?: boolean}} ctx
+ * @param {string[]} rest
+ */
+export async function migrateCommand(ctx, rest) {
+  const args = parseArgs(rest);
+  if (args.help) {
+    printHelp();
+    process.exit(EXIT_OK);
+  }
+
+  const cwd = args.cwd || process.cwd();
+  let read;
+  try {
+    read = readConfig(cwd);
+  } catch (err) {
+    die(EXIT_USAGE, err instanceof Error ? err.message : String(err));
+  }
+
+  const { config: src, filePath } = read;
+
+  let result;
+  try {
+    result = migrateV1ToV2(src);
+  } catch (err) {
+    die(EXIT_USAGE, `migrate failed: ${err instanceof Error ? err.message : err}`);
+  }
+
+  if (!result.migrated) {
+    const payload = {
+      path: filePath,
+      migrated: false,
+      warnings: result.warnings,
+      stub_lanes: [],
+    };
+    if (ctx.json || args.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(`${filePath}: already at the latest schema (no changes).`);
+    }
+    process.exit(EXIT_NOOP);
+  }
+
+  const validation = validateConfig(result.config);
+  if (!validation.ok) {
+    const msg = [
+      "migrate produced an invalid v2 config:",
+      ...validation.errors.map((e) => `  - ${e}`),
+      ...result.warnings.map((w) => `  (warn) ${w}`),
+    ].join("\n");
+    die(EXIT_VALIDATION, msg);
+  }
+
+  const yes = ctx.yes || args.yes;
+  const dryRun = ctx.dryRun || args.dryRun;
+  const backupPath = `${filePath}.bak`;
+
+  if (dryRun || !yes) {
+    const summary = {
+      path: filePath,
+      migrated: true,
+      backup: backupPath,
+      dry_run: Boolean(dryRun),
+      warnings: result.warnings,
+      stub_lanes: result.stub_lanes,
+    };
+    if (ctx.json || args.json) {
+      console.log(
+        JSON.stringify(
+          { ...summary, proposed_config: result.config },
+          null,
+          2,
+        ),
+      );
+    } else {
+      console.log(`Proposed migration for ${filePath}:`);
+      for (const w of result.warnings) console.log(`  - ${w}`);
+      if (result.stub_lanes.length) {
+        console.log(`  - stub lanes (fill before shipping): ${result.stub_lanes.join(", ")}`);
+      }
+      console.log("");
+      console.log(serialiseForDisplay(result.config));
+      console.log("");
+      if (dryRun) {
+        console.log("--dry-run: not writing to disk.");
+      } else {
+        console.log("Re-run with --yes to apply the migration (writes .bak first).");
+      }
+    }
+    process.exit(EXIT_OK);
+  }
+
+  try {
+    fs.copyFileSync(filePath, backupPath);
+    writeConfig(filePath, result.config);
+  } catch (err) {
+    die(EXIT_USAGE, `migrate write failed: ${err instanceof Error ? err.message : err}`);
+  }
+
+  if (ctx.json || args.json) {
+    console.log(
+      JSON.stringify(
+        {
+          path: filePath,
+          migrated: true,
+          backup: backupPath,
+          warnings: result.warnings,
+          stub_lanes: result.stub_lanes,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log(`Wrote ${filePath} (backup at ${backupPath}).`);
+    for (const w of result.warnings) console.log(`  - ${w}`);
+    if (result.stub_lanes.length) {
+      console.log(
+        `  - stub lanes to finish: ${result.stub_lanes.join(", ")} — edit the file or rerun 'shipctl init'.`,
+      );
+    }
+  }
+  process.exit(EXIT_OK);
+}
+
+function parseArgs(rest) {
+  const out = { dryRun: false, yes: false, json: false, help: false, cwd: null };
+  const copy = [...rest];
+  while (copy.length) {
+    const a = copy.shift();
+    if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--yes") out.yes = true;
+    else if (a === "--json") out.json = true;
+    else if (a === "--cwd" && copy[0] !== undefined) out.cwd = path.resolve(String(copy.shift()));
+    else if (a && a.startsWith("--cwd=")) out.cwd = path.resolve(a.slice("--cwd=".length));
+    else {
+      console.error(`unknown argument: ${a}\nRun: shipctl migrate --help`);
+      process.exit(EXIT_USAGE);
+    }
+  }
+  return out;
+}
+
+/**
+ * Render the config as YAML-ish for display. We deliberately don't
+ * import the YAML module here — the real write path already
+ * normalises, and `--dry-run` is human-scan territory. JSON is good
+ * enough and shows every field unambiguously.
+ */
+function serialiseForDisplay(config) {
+  return JSON.stringify(config, null, 2);
+}
+
+function die(code, msg) {
+  console.error(msg);
+  process.exit(code);
+}