@elmundi/ship-cli 0.8.0 → 0.11.2

package/lib/verify/checks/rules-markers.mjs

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { KNOWN_AGENTS } from "../../detect.mjs";
+import { listCached, readCachedArtifact } from "../../cache/store.mjs";
+
+export const id = "rules-markers";
+export const category = "local";
+export const description = "Agent rule files contain current artifacts-protocol markers";
+
+const RULE_MARKER = "<!-- ship-cli: artifacts-protocol v1 -->";
+const FOOTER_PREFIX = "<!-- ship-cli: installed-from ";
+const FOOTER_SUFFIX = " -->";
+
+function readFooter(body) {
+  const idx = body.lastIndexOf(FOOTER_PREFIX);
+  if (idx < 0) return null;
+  const end = body.indexOf(FOOTER_SUFFIX, idx);
+  if (end < 0) return null;
+  return body.slice(idx + FOOTER_PREFIX.length, end).trim();
+}
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const agents = (ctx.config && ctx.config.stack && Array.isArray(ctx.config.stack.agents))
+    ? ctx.config.stack.agents
+    : [];
+  if (!agents.length) {
+    return { status: "skip", detail: "stack.agents is empty" };
+  }
+
+  let cache = [];
+  try {
+    cache = listCached(ctx.cwd);
+  } catch {
+    cache = [];
+  }
+
+  const rows = [];
+  let hasFail = false;
+  let hasWarn = false;
+
+  for (const agent of agents) {
+    const spec = KNOWN_AGENTS[agent];
+    // Prefer the install_target declared by the cached agent-rules artifact;
+    // fall back to the hardcoded KNOWN_AGENTS mapping for graceful
+    // degradation when the cache hasn't been populated yet (RFC-0004).
+    let rel = null;
+    let cachedFm = null;
+    try {
+      cachedFm = readCachedArtifact(ctx.cwd, "collection", `agent-rules-${agent}`);
+    } catch {
+      cachedFm = null;
+    }
+    if (!cachedFm) {
+      rows.push({
+        agent,
+        status: "warn",
+        detail: `no cached agent-rules-${agent}; run shipctl sync`,
+      });
+      hasWarn = true;
+      continue;
+    }
+    // v1 single-file artifacts kept install_target at the top level; v2
+    // moved it under `spec:`. Honour both.
+    const topLevel = cachedFm.fm && typeof cachedFm.fm.install_target === "string"
+      ? cachedFm.fm.install_target.trim()
+      : "";
+    const nested = cachedFm.spec && typeof cachedFm.spec.install_target === "string"
+      ? cachedFm.spec.install_target.trim()
+      : "";
+    const installTarget = topLevel || nested;
+    if (installTarget) {
+      rel = installTarget;
+    } else if (spec) {
+      rel = path.join(...spec.targetRel);
+    } else {
+      rows.push({ agent, status: "warn", detail: `unknown agent id '${agent}' (no install_target and no KNOWN_AGENTS entry)` });
+      hasWarn = true;
+      continue;
+    }
+
+    const abs = path.join(ctx.cwd, rel);
+    if (!fs.existsSync(abs)) {
+      rows.push({ agent, status: "fail", detail: `missing rule file ${rel}` });
+      hasFail = true;
+      continue;
+    }
+    const body = fs.readFileSync(abs, "utf8");
+    if (!body.includes(RULE_MARKER)) {
+      rows.push({ agent, status: "fail", detail: `${rel} has no '${RULE_MARKER}' marker` });
+      hasFail = true;
+      continue;
+    }
+    const footer = readFooter(body);
+    if (!footer) {
+      rows.push({ agent, status: "fail", detail: `${rel} has no 'installed-from' footer` });
+      hasFail = true;
+      continue;
+    }
+
+    // footer looks like "collection/agent-rules-cursor@1.0.1"
+    const m = /^collection\/agent-rules-[a-z0-9-]+@([0-9A-Za-z.\-+]+)$/.exec(footer);
+    if (!m) {
+      rows.push({ agent, status: "warn", detail: `${rel} footer is '${footer}' (non-standard format)` });
+      hasWarn = true;
+      continue;
+    }
+    const installedVersion = m[1];
+    const cached = cache.find(
+      (c) => c.kind === "collection" && c.id === `agent-rules-${agent}`,
+    );
+    if (cached && cached.version && cached.version !== installedVersion) {
+      rows.push({
+        agent,
+        status: "warn",
+        detail: `${rel} footer @${installedVersion}, cache has @${cached.version} — run 'shipctl init --copy-rules'`,
+      });
+      hasWarn = true;
+    } else {
+      rows.push({ agent, status: "pass", detail: `${rel} @${installedVersion}` });
+    }
+  }
+
+  const overall = hasFail ? "fail" : hasWarn ? "warn" : "pass";
+  const summary = rows
+    .filter((r) => r.status !== "pass")
+    .map((r) => `${r.agent}: ${r.detail}`)
+    .join("; ");
+  const detail = overall === "pass"
+    ? `all ${rows.length} agent rule files have correct markers`
+    : summary || `${rows.length} agent rule files inspected`;
+  return { status: overall, detail, data: { rows } };
+}

package/lib/verify/checks/stack-enums.mjs

@@ -0,0 +1,33 @@
+import { validateConfig } from "../../config/schema.mjs";
+
+export const id = "stack-enums";
+export const category = "config";
+export const description = "stack.* values are valid enum members";
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  if (!ctx.config) {
+    return { status: "skip", detail: "no config loaded" };
+  }
+  const res = validateConfig(ctx.config);
+  if (!res.ok) {
+    const stackErrors = res.errors.filter((e) => e.startsWith("stack."));
+    const display = stackErrors.length ? stackErrors : res.errors;
+    return {
+      status: "fail",
+      detail: display[0],
+      data: { errors: res.errors, warnings: res.warnings },
+    };
+  }
+  const warns = (res.warnings || []).filter((w) => w.startsWith("stack."));
+  if (warns.length) {
+    return { status: "warn", detail: warns[0], data: { warnings: res.warnings } };
+  }
+  const stack = ctx.config.stack || {};
+  return {
+    status: "pass",
+    detail: `tracker=${stack.tracker || "?"}, ci=${stack.ci || "?"}, preset=${stack.preset || "?"}, language=${stack.language || "?"}, agents=[${(stack.agents || []).join(",") || ""}]`,
+  };
+}

package/lib/verify/checks/tracker-labels.mjs

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+export const id = "tracker-labels";
+export const category = "network";
+export const description = "Tracker labels match .ship/labels.yml";
+
+async function fetchLinearLabels(apiKey) {
+  const body = JSON.stringify({
+    query: "query { issueLabels(first: 250) { nodes { id name } } }",
+  });
+  const res = await fetch("https://api.linear.app/graphql", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      Authorization: apiKey,
+    },
+    body,
+  });
+  if (!res.ok) {
+    throw new Error(`Linear API ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  const nodes = data?.data?.issueLabels?.nodes || [];
+  return nodes.map((n) => String(n.name));
+}
+
+function readLabelsYaml(cwd) {
+  const rel = path.join(".ship", "labels.yml");
+  const abs = path.join(cwd, rel);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    const doc = YAML.parse(fs.readFileSync(abs, "utf8"));
+    const arr = Array.isArray(doc?.labels) ? doc.labels : [];
+    return arr.map((l) => (typeof l === "string" ? l : l && l.name)).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {import("../registry.mjs").CheckContext} ctx
+ */
+export async function run(ctx) {
+  const tracker = ctx.config && ctx.config.stack && ctx.config.stack.tracker;
+  if (!tracker || tracker === "none") {
+    return { status: "skip", detail: "stack.tracker is none" };
+  }
+  if (tracker !== "linear") {
+    return {
+      status: "skip",
+      detail: `tracker=${tracker} label verification not implemented yet`,
+    };
+  }
+
+  const declared = readLabelsYaml(ctx.cwd);
+  if (declared == null) {
+    return { status: "skip", detail: ".ship/labels.yml not present" };
+  }
+
+  const apiKey = process.env.LINEAR_API_KEY;
+  if (!apiKey) {
+    return {
+      status: "skip",
+      detail: "LINEAR_API_KEY not set — skipping live Linear label fetch",
+    };
+  }
+
+  let remote;
+  try {
+    remote = await fetchLinearLabels(apiKey);
+  } catch (e) {
+    return { status: "warn", detail: `Linear API call failed: ${e.message}` };
+  }
+
+  const remoteSet = new Set(remote);
+  const missing = declared.filter((n) => !remoteSet.has(n));
+  if (!missing.length) {
+    return {
+      status: "pass",
+      detail: `all ${declared.length} declared labels exist on Linear`,
+    };
+  }
+  return {
+    status: "warn",
+    detail: `missing labels on Linear: ${missing.join(", ")}`,
+    data: { missing, declared, remote_count: remote.length },
+  };
+}

package/lib/verify/registry.mjs

@@ -0,0 +1,120 @@
+/**
+ * Verify registry: central import point for all Ship verify checks.
+ *
+ * @typedef {Object} CheckContext
+ * @property {string} cwd
+ * @property {object|null} config       Parsed .ship/config.yml (or null if missing).
+ * @property {object|null} [inventory]  Optional .ship/inventory.json snapshot.
+ * @property {string} [baseUrl]         Effective methodology API base URL.
+ * @property {(msg:string)=>void} [logger]
+ *
+ * @typedef {"pass"|"warn"|"fail"|"skip"} CheckStatus
+ *
+ * @typedef {Object} CheckResult
+ * @property {CheckStatus} status
+ * @property {string} detail
+ * @property {object} [data]
+ *
+ * @typedef {Object} Check
+ * @property {string} id
+ * @property {"local"|"config"|"network"} category
+ * @property {string} description
+ * @property {(ctx:CheckContext)=>Promise<CheckResult>} run
+ */
+
+import * as configPresent from "./checks/config-present.mjs";
+import * as gitignoreCache from "./checks/gitignore-cache.mjs";
+import * as rulesMarkers from "./checks/rules-markers.mjs";
+import * as cacheIntegrity from "./checks/cache-integrity.mjs";
+import * as bootstrapFiles from "./checks/bootstrap-files.mjs";
+import * as stackEnums from "./checks/stack-enums.mjs";
+import * as agentsOnDisk from "./checks/agents-on-disk.mjs";
+import * as apiReachable from "./checks/api-reachable.mjs";
+import * as artifactsUpToDate from "./checks/artifacts-up-to-date.mjs";
+import * as trackerLabels from "./checks/tracker-labels.mjs";
+import * as ciSecrets from "./checks/ci-secrets.mjs";
+
+/**
+ * Ordered list of checks. Order governs how they appear in `shipctl verify`
+ * output; within a category we keep a stable human-friendly grouping.
+ * @type {Check[]}
+ */
+const CHECKS = [
+  configPresent,
+  gitignoreCache,
+  stackEnums,
+  rulesMarkers,
+  cacheIntegrity,
+  bootstrapFiles,
+  agentsOnDisk,
+  apiReachable,
+  artifactsUpToDate,
+  trackerLabels,
+  ciSecrets,
+];
+
+export function allChecks() {
+  return CHECKS.slice();
+}
+
+/**
+ * @param {CheckContext} ctx
+ * @param {{filter?:string[]|null, noNetwork?:boolean}} [opts]
+ * @returns {Promise<Array<{id:string, category:string, description:string, status:CheckStatus, detail:string, data?:object, duration_ms:number}>>}
+ */
+export async function runChecks(ctx, opts = {}) {
+  const { filter = null, noNetwork = false } = opts;
+  const wantSet = filter && filter.length
+    ? new Set(filter.map((s) => String(s).trim()).filter(Boolean))
+    : null;
+
+  const out = [];
+  for (const check of CHECKS) {
+    if (wantSet && !wantSet.has(check.id)) continue;
+    if (noNetwork && check.category === "network") {
+      out.push({
+        id: check.id,
+        category: check.category,
+        description: check.description,
+        status: "skip",
+        detail: "skipped (--no-network)",
+        duration_ms: 0,
+      });
+      continue;
+    }
+    const started = Date.now();
+    let res;
+    try {
+      res = await check.run(ctx);
+    } catch (e) {
+      res = {
+        status: "fail",
+        detail: `check threw: ${e instanceof Error ? e.message : String(e)}`,
+      };
+    }
+    out.push({
+      id: check.id,
+      category: check.category,
+      description: check.description,
+      status: res.status || "fail",
+      detail: res.detail || "",
+      data: res.data,
+      duration_ms: Date.now() - started,
+    });
+  }
+  return out;
+}
+
+/**
+ * Summarise a list of CheckResult rows.
+ */
+export function summarize(rows) {
+  const summary = { total: rows.length, pass: 0, warn: 0, fail: 0, skip: 0 };
+  for (const r of rows) {
+    if (r.status === "pass") summary.pass += 1;
+    else if (r.status === "warn") summary.warn += 1;
+    else if (r.status === "fail") summary.fail += 1;
+    else summary.skip += 1;
+  }
+  return summary;
+}

package/lib/version.mjs

@@ -0,0 +1,34 @@
+/**
+ * Read the CLI version straight from the published package.json so we never
+ * end up with a hardcoded constant that drifts from npm. The value is also
+ * the canonical Ship release version (kept in sync with the root VERSION
+ * file by `scripts/version.mjs` — see top-level README "Versioning").
+ *
+ * Used by:
+ *   - `shipctl --version` / `shipctl -v` / `shipctl version`
+ *   - the `User-Agent` header on every outbound HTTP request, so the
+ *     methodology API can correlate adoption metrics with the client release.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(__dirname, "..", "package.json");
+
+let cached = null;
+
+export function getCliVersion() {
+  if (cached) return cached;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    cached = String(pkg.version || "0.0.0-unknown");
+  } catch {
+    cached = "0.0.0-unknown";
+  }
+  return cached;
+}
+
+export function getUserAgent() {
+  return `shipctl/${getCliVersion()} (+https://github.com/ElMundiUA/ship)`;
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.8.0",
+  "version": "0.11.2",
   "type": "module",
-  "description": "Ship CLI — methodology search, docs fetch/feedback, catalog commands (pattern/tool/workflow/collection), and agent init",
+  "description": "Ship CLI — artifacts protocol (patterns/tools/workflows/collections), docs search/fetch/feedback, and agent init",
   "license": "Apache-2.0",
   "author": "Denys Kuzin",
   "repository": {
@@ -19,6 +19,7 @@
   },
   "keywords": [
     "ship",
+    "shipctl",
     "cli",
     "agents",
     "methodology"
@@ -31,6 +32,12 @@
     "access": "public"
   },
   "bin": {
-    "ship": "./bin/ship.mjs"
+    "shipctl": "./bin/shipctl.mjs"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3"
   }
 }

package/bin/ship.mjs

@@ -1,68 +0,0 @@
-#!/usr/bin/env node
-import { extractGlobalArgv } from "../lib/config.mjs";
-import { docsCommand } from "../lib/commands/docs.mjs";
-import { searchCommand } from "../lib/commands/search.mjs";
-import { patternCommand } from "../lib/commands/patterns.mjs";
-import { resourceManifestCommand } from "../lib/commands/manifest-catalog.mjs";
-import { printHelp } from "../lib/commands/help.mjs";
-import { initCommand } from "../lib/commands/init.mjs";
-
-const raw = process.argv.slice(2);
-const { _, ...g } = extractGlobalArgv(raw);
-const ctx = {
-  baseUrl: g.baseUrl,
-  json: g.json,
-  yes: g.yes,
-  force: g.force,
-  dryRun: g.dryRun,
-};
-
-const [cmd, ...rest] = _;
-
-try {
-  if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
-    printHelp();
-    process.exit(0);
-  }
-
-  if (cmd === "search") {
-    await searchCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "docs") {
-    await docsCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "pattern" || cmd === "patterns") {
-    await patternCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "tool" || cmd === "tools") {
-    await resourceManifestCommand("tool", ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "workflow" || cmd === "workflows") {
-    await resourceManifestCommand("workflow", ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "collection" || cmd === "collections") {
-    await resourceManifestCommand("collection", ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "init") {
-    await initCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  console.error(`Unknown command: ${cmd}\nRun: ship help`);
-  process.exit(1);
-} catch (err) {
-  console.error(err instanceof Error ? err.message : err);
-  process.exit(1);
-}