@metasession.co/devaudit-cli 0.1.54 → 0.1.56

package/README.md

@@ -6,9 +6,21 @@ This is the source of `@metasession.co/devaudit-cli` (binary name: `devaudit`).
 
 ## Install
 
+`npx` is the canonical zero-install invocation — pulls the latest version on first run:
+
+```bash
+npx @metasession.co/devaudit-cli@latest --help
+npx @metasession.co/devaudit-cli@latest install ../path/to/your-project
+npx @metasession.co/devaudit-cli@latest update
+```
+
+Prefer a permanent install? Run once, then the short forms work everywhere:
+
 ```bash
 npm install -g @metasession.co/devaudit-cli
 devaudit --help
+devaudit install ../path/to/your-project
+devaudit update
 ```
 
 Requires Node ≥ 22. Native binaries (no Node runtime needed) are on the roadmap.
@@ -71,15 +83,11 @@ cli/
         └── version.ts        # CLI version constant
 ```
 
-Future structure (per [build-plan.md](../docs/devaudit-cli/build-plan.md)): `src/commands/{install,update,push,auth/*,org/*,plugin/*,config/*,status,upgrade}.ts` and `src/lib/{adapter,devaudit-api,sdlc-config,auth,git-provider,policy,plugin,report,prompts,paths,stack-detect}.ts`.
-
 ## Why a CLI (it replaced the original bash scripts)
 
 - Cross-platform native (Linux/macOS/Windows; no WSL requirement)
 - JSON output mode on every command for CI
 - Interactive UX comparable to Vercel/Supabase/Firebase/GH/Railway CLIs
-- Single-binary distribution via Node SEA (no Node runtime required on the user's machine)
-- Plugin extensibility
+- Plugin extensibility (`@metasession.co/devaudit-plugin-sdk` defines the contract; `@metasession.co/devaudit-plugin-prisma` + `@metasession.co/devaudit-plugin-evidence-export` are first-party reference implementations)
 - Organisation-level features: policy-as-code, RBAC, centralised reporting
-
-The full motivation lives in [`../docs/devaudit-cli/README.md`](../docs/devaudit-cli/README.md).
+- Single-binary distribution via Node SEA (no Node runtime required on the user's machine) — on the roadmap

package/dist/index.js

@@ -8,6 +8,7 @@ import envPaths from 'env-paths';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { validateManifest } from '@metasession.co/devaudit-plugin-sdk';
 import * as clack2 from '@clack/prompts';
+import Ajv from 'ajv';
 import { readdir, readFile, writeFile } from 'fs/promises';
 
 var DEFAULT_OPTIONS = { json: false, verbose: false, noColor: false };
@@ -55,7 +56,7 @@ function emitJsonResult(payload) {
 
 // package.json
 var package_default = {
-  version: "0.1.54"};
+  version: "0.1.56"};
 
 // src/lib/version.ts
 var CLI_VERSION = package_default.version;
@@ -594,27 +595,62 @@ async function runStatus(options) {
   }
 }
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
-var MAX_ATTEMPTS = 3;
+var DEFAULT_MAX_ATTEMPTS = 5;
 var INITIAL_BACKOFF_MS = 1e3;
+function maxAttempts() {
+  const raw = Number.parseInt(process.env["UPLOAD_MAX_ATTEMPTS"] ?? "", 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MAX_ATTEMPTS;
+}
 async function collectFiles(filePath) {
   const stat = await promises.stat(filePath);
   if (stat.isFile()) return [filePath];
   if (stat.isDirectory()) {
-    const entries = await promises.readdir(filePath, { withFileTypes: true });
     const files = [];
+    const entries = await promises.readdir(filePath, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isFile()) files.push(join(filePath, entry.name));
+      const child = join(filePath, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...await collectFiles(child));
+      } else if (entry.isFile()) {
+        files.push(child);
+      }
     }
     return files;
   }
   throw new Error(`${filePath} is neither a file nor a directory.`);
 }
+var STUB_BANNER = /STARTER TEMPLATE.+REPLACE BEFORE/;
+function isUneditedStub(buf) {
+  return STUB_BANNER.test(buf.toString("utf-8"));
+}
 function delay(ms) {
   return new Promise((res) => setTimeout(res, ms));
 }
-async function uploadOne(file, opts) {
+async function probeBaseUrlDrift(baseUrl) {
+  try {
+    const probeUrl = `${baseUrl.replace(/\/$/, "")}/api/health`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1e4);
+    let res;
+    try {
+      res = await fetch(probeUrl, { method: "HEAD", redirect: "manual", signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (res.status < 300 || res.status >= 400) return null;
+    const location = res.headers.get("location");
+    if (!location) return null;
+    const oldHost = new URL(baseUrl).host;
+    const newHost = new URL(location, baseUrl).host;
+    if (!newHost || oldHost === newHost) return null;
+    return `DEVAUDIT_BASE_URL host '${oldHost}' redirects to '${newHost}'. Rotate the DEVAUDIT_BASE_URL secret to the new host to avoid silent breakage (uploads still succeed this run). Ref: https://github.com/metasession-dev/DevAudit-Installer/issues/143`;
+  } catch {
+    return null;
+  }
+}
+async function uploadOne(file, buf, opts) {
+  const attempts = maxAttempts();
   const form = new FormData();
-  const buf = await promises.readFile(file);
   const blob = new Blob([new Uint8Array(buf)]);
   form.set("file", blob, basename(file));
   form.set("projectSlug", opts.projectSlug);
@@ -625,10 +661,14 @@ async function uploadOne(file, opts) {
   if (opts.createReleaseIfMissing) form.set("createReleaseIfMissing", "true");
   if (opts.environment) form.set("environment", opts.environment);
   if (opts.evidenceCategory) form.set("evidenceCategory", opts.evidenceCategory);
+  if (opts.releaseBranch) form.set("releaseBranch", opts.releaseBranch);
+  if (opts.releaseTitle) form.set("releaseTitle", opts.releaseTitle);
+  if (opts.changeType) form.set("changeType", opts.changeType);
+  if (opts.gateStatus) form.set("gateStatus", opts.gateStatus);
   const url = `${opts.baseUrl.replace(/\/$/, "")}/api/evidence/upload`;
   let attempt = 1;
   let backoff = INITIAL_BACKOFF_MS;
-  while (attempt <= MAX_ATTEMPTS) {
+  while (attempt <= attempts) {
     const res = await fetch(url, {
       method: "POST",
       headers: { authorization: `Bearer ${opts.apiKey}` },
@@ -638,7 +678,7 @@ async function uploadOne(file, opts) {
       const body = await res.json().catch(() => null);
       return { file, ok: true, status: res.status, body };
     }
-    if (RETRYABLE_STATUSES.has(res.status) && attempt < MAX_ATTEMPTS) {
+    if (RETRYABLE_STATUSES.has(res.status) && attempt < attempts) {
       const retryAfter = Number.parseInt(res.headers.get("retry-after") ?? "", 10);
       const wait = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : backoff;
       await delay(wait);
@@ -658,7 +698,12 @@ async function uploadEvidence(opts) {
   }
   const results = [];
   for (const file of files) {
-    results.push(await uploadOne(file, opts));
+    const buf = await promises.readFile(file);
+    if (isUneditedStub(buf)) {
+      results.push({ file, ok: true, status: 0, skipped: true });
+      continue;
+    }
+    results.push(await uploadOne(file, buf, opts));
   }
   return results;
 }
@@ -670,8 +715,24 @@ function buildMetadata(options) {
   if (options.gitSha) metadata["gitSha"] = options.gitSha;
   if (options.ciRunId) metadata["ciRunId"] = options.ciRunId;
   if (options.branch) metadata["branch"] = options.branch;
+  for (const kv of options.metaKeys ?? []) {
+    const eq = kv.indexOf("=");
+    metadata[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
   return metadata;
 }
+function validateOptions(options) {
+  if (options.environment && !options.release) {
+    return "--environment requires --release (evidence without a release is orphaned)";
+  }
+  if (options.release && !options.category) {
+    return "--category is required when --release is specified (gate validation)";
+  }
+  for (const kv of options.metaKeys ?? []) {
+    if (!kv.includes("=")) return `--meta-key requires key=value (got: ${kv})`;
+  }
+  return null;
+}
 async function runDryRun(options, baseUrl) {
   const log = logger();
   const files = await collectFiles(options.filePath);
@@ -700,6 +761,12 @@ async function runPush(options) {
   const log = logger();
   const projectPath = resolve(process.cwd());
   const baseUrl = options.baseUrl ?? process.env["DEVAUDIT_BASE_URL"] ?? DEFAULT_BASE_URL3;
+  const validationError = validateOptions(options);
+  if (validationError) {
+    if (isJsonMode()) emitJsonResult({ ok: false, reason: "invalid_arguments", message: validationError });
+    else log.error(validationError);
+    process.exit(2);
+  }
   if (options.dryRun) {
     await runDryRun(options, baseUrl);
     return;
@@ -716,6 +783,8 @@ async function runPush(options) {
   log.info(
     `Uploading ${options.filePath} (project=${options.projectSlug} req=${options.requirementId} type=${options.evidenceType}) \u2192 ${baseUrl}`
   );
+  const driftWarning = await probeBaseUrlDrift(baseUrl);
+  if (driftWarning) log.warn(driftWarning);
   const plugins = options.plugins ?? (await discoverPlugins()).loaded;
   if (plugins.length > 0) {
     const ctx = await buildPluginContext({ projectPath });
@@ -733,12 +802,20 @@ async function runPush(options) {
     ...options.createReleaseIfMissing !== void 0 ? { createReleaseIfMissing: options.createReleaseIfMissing } : {},
     ...options.environment !== void 0 ? { environment: options.environment } : {},
     ...options.category !== void 0 ? { evidenceCategory: options.category } : {},
+    ...options.branch !== void 0 ? { releaseBranch: options.branch } : {},
+    ...options.releaseTitle !== void 0 ? { releaseTitle: options.releaseTitle } : {},
+    ...options.changeType !== void 0 ? { changeType: options.changeType } : {},
+    ...options.gateStatus !== void 0 ? { gateStatus: options.gateStatus } : {},
     metadata
   });
   let okCount = 0;
   let failCount = 0;
+  let skippedCount = 0;
   for (const result of results) {
-    if (result.ok) {
+    if (result.skipped) {
+      skippedCount++;
+      log.warn(`  \u2298 ${result.file} SKIPPED \u2014 unedited starter stub (replace the STARTER TEMPLATE banner to upload)`);
+    } else if (result.ok) {
       okCount++;
       log.success(`  \u2713 ${result.file} (HTTP ${result.status})`);
     } else {
@@ -747,7 +824,7 @@ async function runPush(options) {
     }
   }
   log.log("");
-  log.info(`Uploaded: ${okCount} succeeded, ${failCount} failed.`);
+  log.info(`Uploaded: ${okCount} succeeded, ${failCount} failed, ${skippedCount} skipped.`);
   if (plugins.length > 0) {
     const ctx = await buildPluginContext({ projectPath });
     await runHook(plugins, "afterPush", ctx);
@@ -757,7 +834,14 @@ async function runPush(options) {
       ok: failCount === 0,
       uploaded: okCount,
       failed: failCount,
-      results: results.map((r) => ({ file: r.file, ok: r.ok, status: r.status, error: r.error ?? null }))
+      skipped: skippedCount,
+      results: results.map((r) => ({
+        file: r.file,
+        ok: r.ok,
+        status: r.status,
+        skipped: r.skipped ?? false,
+        error: r.error ?? null
+      }))
     });
   }
   if (failCount > 0) process.exit(4);
@@ -1488,10 +1572,44 @@ async function configureBranchProtection(ctx, provider) {
     message: `${result.message ?? "branch-protection apply failed"} \u2014 configure manually`
   };
 }
+var ajv = new Ajv({ allErrors: true, strict: false });
+var validatorCache = /* @__PURE__ */ new Map();
+async function getValidator(schemaPath) {
+  const cached = validatorCache.get(schemaPath);
+  if (cached) return cached;
+  let schema;
+  try {
+    schema = JSON.parse(await promises.readFile(schemaPath, "utf-8"));
+  } catch {
+    return null;
+  }
+  delete schema["$id"];
+  const validate = ajv.compile(schema);
+  validatorCache.set(schemaPath, validate);
+  return validate;
+}
+function formatErrors(validate) {
+  return (validate.errors ?? []).map((e) => `  - ${e.instancePath === "" ? "(root)" : e.instancePath} ${e.message ?? "is invalid"}`).join("\n");
+}
+async function loadAdapter(adapterPath, schemaPath, kind) {
+  const raw = await promises.readFile(adapterPath, "utf-8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${kind} adapter ${adapterPath}: ${err.message}`);
+  }
+  const validate = await getValidator(schemaPath);
+  if (validate && !validate(parsed)) {
+    throw new Error(`${kind} adapter ${adapterPath} failed schema validation:
+${formatErrors(validate)}`);
+  }
+  return parsed;
+}
 async function loadStackAdapter(installerRoot, stack) {
-  const path = join(installerRoot, "sdlc", "files", "stacks", stack, "adapter.json");
-  const raw = await promises.readFile(path, "utf-8");
-  return JSON.parse(raw);
+  const adapterPath = join(installerRoot, "sdlc", "files", "stacks", stack, "adapter.json");
+  const schemaPath = join(installerRoot, "sdlc", "files", "stacks", "_schema", "adapter.schema.json");
+  return loadAdapter(adapterPath, schemaPath, "Stack");
 }
 async function listStacks(installerRoot) {
   const dir = join(installerRoot, "sdlc", "files", "stacks");
@@ -2438,8 +2556,6 @@ async function runJoinCommand(options) {
     process.exit(1);
   }
 }
-
-// src/commands/update.ts
 async function runUpdate(options) {
   const log = logger();
   if (options.version) {
@@ -2449,6 +2565,14 @@ async function runUpdate(options) {
     log.error("No project paths provided. Usage: devaudit update <version> <path> [path...]");
     process.exit(2);
   }
+  if (options.dryRun) {
+    log.warn("DRY RUN \u2014 no files will be written and no plugin hooks will fire");
+    for (const projectPath of options.paths) {
+      log.info(`  [dry-run] would sync SDLC templates via syncProject() against ${resolve(projectPath)}`);
+    }
+    log.success("=== Dry run complete (no mutations performed) ===");
+    return;
+  }
   const plugins = options.plugins ?? (await discoverPlugins()).loaded;
   for (const projectPath of options.paths) {
     if (plugins.length > 0) {
@@ -2556,7 +2680,9 @@ function makeStub(info) {
     if (info.trackedIn) {
       log.info(`Tracked in: ${info.trackedIn}`);
     }
-    log.info("See ./docs/devaudit-cli/build-plan.md for the full implementation plan.");
+    log.info(
+      "File an issue at https://github.com/metasession-dev/DevAudit-Installer/issues if you need this command."
+    );
     process.exit(1);
   };
 }
@@ -2773,7 +2899,7 @@ async function main(argv) {
   });
   program.command("update [version] [paths...]").description(
     "Sync framework templates into existing consumer(s). Both args are optional: paths default to the current directory, and version is a cosmetic label (defaults to the running CLI version). So a bare `devaudit update` syncs the current project."
-  ).action(async (version, paths2) => {
+  ).action(async (version, paths2, cmd) => {
     let resolvedVersion = version;
     let resolvedPaths = paths2 ?? [];
     const looksLikeVersion = (s) => /^v?\d+(\.\d+)/.test(s);
@@ -2782,9 +2908,19 @@ async function main(argv) {
       resolvedVersion = void 0;
     }
     if (resolvedPaths.length === 0) resolvedPaths = ["."];
-    await runUpdate({ version: resolvedVersion ?? CLI_VERSION, paths: resolvedPaths });
+    const globals = cmd.optsWithGlobals();
+    await runUpdate({
+      version: resolvedVersion ?? CLI_VERSION,
+      paths: resolvedPaths,
+      ...globals.dryRun !== void 0 ? { dryRun: Boolean(globals.dryRun) } : {}
+    });
   });
-  program.command("push <project-slug> <requirement-id> <evidence-type> <file>").description("Upload evidence file(s) to DevAudit (port of scripts/upload-evidence.sh)").option("--release <version>", "release version (e.g. v1.0.0)").option("--create-release-if-missing", "auto-create the release as 'draft' if absent").option("--environment <env>", "uat | production").option("--category <cat>", "ci_pipeline | local_dev | planning | test_report | security_scan | release_artifact").option("--git-sha <sha>", "attached to metadata.gitSha").option("--ci-run-id <id>", "attached to metadata.ciRunId").option("--branch <name>", "attached to metadata.branch").option("--base-url <url>", "override portal URL (defaults to DEVAUDIT_BASE_URL env or production)").option("--api-key <key>", "override DEVAUDIT_API_KEY env var").action(
+  program.command("push <project-slug> <requirement-id> <evidence-type> <file>").description("Upload evidence file(s) to DevAudit (port of scripts/upload-evidence.sh)").option("--release <version>", "release version (e.g. v1.0.0)").option("--create-release-if-missing", "auto-create the release as 'draft' if absent").option("--environment <env>", "uat | production").option("--category <cat>", "ci_pipeline | local_dev | planning | test_report | security_scan | release_artifact").option("--git-sha <sha>", "attached to metadata.gitSha").option("--ci-run-id <id>", "attached to metadata.ciRunId").option("--branch <name>", "git branch \u2014 sent as releaseBranch + metadata.branch").option("--release-title <text>", "human title for the release row (releaseTitle; portal no-clobbers)").option("--change-type <type>", "conventional-commit prefix for the release row (changeType)").option("--gate-status <status>", "passed | failed | skipped (gateStatus)").option(
+    "--meta-key <pair>",
+    "repeatable key=value merged into the metadata JSON",
+    (val, acc) => [...acc, val],
+    []
+  ).option("--base-url <url>", "override portal URL (defaults to DEVAUDIT_BASE_URL env or production)").option("--api-key <key>", "override DEVAUDIT_API_KEY env var").action(
     async (projectSlug, requirementId, evidenceType, file, opts, cmd) => {
       const globals = cmd.optsWithGlobals();
       await runPush({
@@ -2799,6 +2935,10 @@ async function main(argv) {
         ...opts.gitSha !== void 0 ? { gitSha: opts.gitSha } : {},
         ...opts.ciRunId !== void 0 ? { ciRunId: opts.ciRunId } : {},
         ...opts.branch !== void 0 ? { branch: opts.branch } : {},
+        ...opts.releaseTitle !== void 0 ? { releaseTitle: opts.releaseTitle } : {},
+        ...opts.changeType !== void 0 ? { changeType: opts.changeType } : {},
+        ...opts.gateStatus !== void 0 ? { gateStatus: opts.gateStatus } : {},
+        ...opts.metaKey !== void 0 && opts.metaKey.length > 0 ? { metaKeys: opts.metaKey } : {},
         ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {},
         ...opts.apiKey !== void 0 ? { apiKey: opts.apiKey } : {},
         ...globals.dryRun !== void 0 ? { dryRun: Boolean(globals.dryRun) } : {}
@@ -2811,7 +2951,7 @@ async function main(argv) {
     const opts = cmd?.optsWithGlobals() ?? {};
     await runBootstrapGovernance({ path, dryRun: opts.dryRun });
   });
-  program.command("doctor").description("Verify the local install: required tools on PATH, auth state, config validity").action(runDoctor);
+  program.command("doctor").description("Verify the local install: required tools on PATH (node>=22, git, gh, jq, curl) + a release close-out drift check").action(runDoctor);
   program.command("status [path]").description("Show the consumer project's framework state").action(async (path) => {
     await runStatus({ path });
   });