@storewright/cli 0.14.0

package/scripts/validate-agent-report.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+import { validateAgentReportAgainstEnvelope } from "../lib/internal/launch-envelope.mjs";
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const value = argv[index + 1];
+    if (arg === "--envelope") {
+      options.envelopePath = value;
+      index += 1;
+    } else if (arg === "--report") {
+      options.reportPath = value;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+export async function validateAgentReportFile({ envelopePath, reportPath }) {
+  if (!envelopePath || !reportPath) {
+    return { ok: false, errors: ["Missing --envelope or --report argument"] };
+  }
+  const envelope = JSON.parse(await readFile(envelopePath, "utf8"));
+  const report = JSON.parse(await readFile(reportPath, "utf8"));
+  return validateAgentReportAgainstEnvelope({ envelope, report });
+}
+
+async function main() {
+  const result = await validateAgentReportFile(parseArgs(process.argv.slice(2)));
+  if (!result.ok) {
+    for (const error of result.errors) {
+      console.error(error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Agent report matches launch envelope.");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/validate-artifact.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(scriptDir);
+
+function parseArgs(argv) {
+  const args = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--schema") {
+      args.schemaPath = argv[index + 1];
+      index += 1;
+    } else if (arg === "--artifact") {
+      args.artifactPath = argv[index + 1];
+      index += 1;
+    }
+  }
+
+  return args;
+}
+
+function resolveReadablePath(filePath) {
+  if (!filePath || existsSync(filePath)) {
+    return filePath;
+  }
+  const packageRelativePrefix = "storewright/";
+  if (filePath.startsWith(packageRelativePrefix)) {
+    const packageRelativePath = filePath.slice(packageRelativePrefix.length);
+    const resolved = join(packageRoot, packageRelativePath);
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+  }
+  return filePath;
+}
+
+async function readJson(filePath, label) {
+  if (!filePath) {
+    return { ok: false, errors: [`Missing --${label} argument`] };
+  }
+
+  const readablePath = resolveReadablePath(filePath);
+  if (!existsSync(readablePath)) {
+    return { ok: false, errors: [`${capitalize(label)} file does not exist: ${filePath}`] };
+  }
+
+  try {
+    return { ok: true, value: JSON.parse(await readFile(readablePath, "utf8")) };
+  } catch (error) {
+    return { ok: false, errors: [`${capitalize(label)} file is not valid JSON: ${error.message}`] };
+  }
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function typeMatches(value, expectedType) {
+  if (expectedType === "array") return Array.isArray(value);
+  if (expectedType === "object") return value !== null && typeof value === "object" && !Array.isArray(value);
+  if (expectedType === "number") return typeof value === "number" && Number.isFinite(value);
+  return typeof value === expectedType;
+}
+
+function validateValue(schema, value, path = "artifact") {
+  const errors = [];
+
+  if (schema.type && !typeMatches(value, schema.type)) {
+    errors.push(`${path} must be ${schema.type}`);
+    return errors;
+  }
+
+  if (Object.hasOwn(schema, "const") && value !== schema.const) {
+    errors.push(`${path} must be ${JSON.stringify(schema.const)}`);
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${path} must be one of: ${schema.enum.join(", ")}`);
+  }
+
+  if (schema.type === "string" && schema.minLength && value.length < schema.minLength) {
+    errors.push(`${path} must be at least ${schema.minLength} character(s)`);
+  }
+
+  if (schema.type === "string" && schema.maxLength && value.length > schema.maxLength) {
+    errors.push(`${path} must be at most ${schema.maxLength} character(s)`);
+  }
+
+  if (schema.type === "string" && schema.pattern && !(new RegExp(schema.pattern).test(value))) {
+    errors.push(`${path} must match pattern ${schema.pattern}`);
+  }
+
+  if (schema.type === "number") {
+    if (Object.hasOwn(schema, "minimum") && value < schema.minimum) {
+      errors.push(`${path} must be >= ${schema.minimum}`);
+    }
+    if (Object.hasOwn(schema, "maximum") && value > schema.maximum) {
+      errors.push(`${path} must be <= ${schema.maximum}`);
+    }
+  }
+
+  if (schema.allOf) {
+    for (const branchSchema of schema.allOf) {
+      errors.push(...validateValue(branchSchema, value, path));
+    }
+  }
+
+  if (schema.anyOf) {
+    const branchErrors = schema.anyOf.map((branchSchema) => validateValue(branchSchema, value, path));
+    if (!branchErrors.some((candidateErrors) => candidateErrors.length === 0)) {
+      const detail = [...new Set(branchErrors.flat())].join("; ");
+      errors.push(`${path} must match at least one anyOf schema${detail ? `: ${detail}` : ""}`);
+    }
+  }
+
+  if (schema.contains && Array.isArray(value)) {
+    const matchCount = value.filter((item, index) => validateValue(schema.contains, item, `${path}[${index}]`).length === 0).length;
+    const minContains = schema.minContains ?? 1;
+    if (matchCount < minContains) {
+      const expectedName = schema.contains?.properties?.name?.const;
+      const suffix = expectedName ? ` (${expectedName})` : "";
+      errors.push(`${path} must contain at least ${minContains} item(s) matching contains schema${suffix}`);
+    }
+  }
+
+  if (schema.type === "array") {
+    if (schema.minItems && value.length < schema.minItems) {
+      errors.push(`${path} must contain at least ${schema.minItems} item(s)`);
+    }
+
+    if (schema.items) {
+      value.forEach((item, index) => {
+        errors.push(...validateValue(schema.items, item, `${path}[${index}]`));
+      });
+    }
+  }
+
+  if (schema.type === "object") {
+    for (const requiredKey of schema.required ?? []) {
+      if (!Object.hasOwn(value, requiredKey)) {
+        errors.push(`${path}.${requiredKey} is required`);
+      }
+    }
+
+    for (const [key, propertySchema] of Object.entries(schema.properties ?? {})) {
+      if (Object.hasOwn(value, key)) {
+        errors.push(...validateValue(propertySchema, value[key], `${path}.${key}`));
+      }
+    }
+
+    if (schema.additionalProperties === false) {
+      const allowed = new Set(Object.keys(schema.properties ?? {}));
+      for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+          errors.push(`${path}.${key} is not allowed`);
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+export async function validateArtifact({ schemaPath, artifactPath }) {
+  const schemaResult = await readJson(schemaPath, "schema");
+  if (!schemaResult.ok) return { ok: false, errors: schemaResult.errors };
+
+  const artifactResult = await readJson(artifactPath, "artifact");
+  if (!artifactResult.ok) return { ok: false, errors: artifactResult.errors };
+
+  const errors = validateValue(schemaResult.value, artifactResult.value);
+  return { ok: errors.length === 0, errors };
+}
+
+async function main() {
+  const result = await validateArtifact(parseArgs(process.argv.slice(2)));
+
+  if (!result.ok) {
+    for (const error of result.errors) {
+      console.error(error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("Artifact is valid.");
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/validate-launch-envelope.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { validateLaunchEnvelope } from "../lib/internal/launch-envelope.mjs";
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const value = argv[index + 1];
+    if (arg === "--envelope") {
+      options.envelopePath = value;
+      index += 1;
+    } else if (arg === "--run-dir") {
+      options.runDir = value;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+export async function validateLaunchEnvelopeFile({
+  packageRoot = join(import.meta.dirname, ".."),
+  runDir,
+  envelopePath
+}) {
+  if (!envelopePath) {
+    return { ok: false, errors: ["Missing --envelope argument"] };
+  }
+  const envelope = JSON.parse(await readFile(envelopePath, "utf8"));
+  return validateLaunchEnvelope({ packageRoot, runDir, envelope });
+}
+
+async function main() {
+  const result = await validateLaunchEnvelopeFile(parseArgs(process.argv.slice(2)));
+  if (!result.ok) {
+    for (const error of result.errors) {
+      console.error(error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Launch envelope is valid.");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/validate-registries.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { validateRegistryConsistency } from "../lib/internal/multi-agent-contracts.mjs";
+
+const defaultPackageRoot = join(import.meta.dirname, "..");
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const value = argv[index + 1];
+    if (arg === "--package-root") {
+      options.packageRoot = value;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+export async function validateRegistries({
+  packageRoot = defaultPackageRoot,
+  requireWorkflowFiles = existsSync(join(packageRoot, "workflows"))
+} = {}) {
+  return validateRegistryConsistency({
+    root: packageRoot,
+    workflowManifestPath: join(packageRoot, "contracts", "workflow-manifest.json"),
+    capabilityRegistryPath: join(packageRoot, "contracts", "capability-registry.json"),
+    actionRegistryPath: join(packageRoot, "contracts", "action-registry.json"),
+    requireWorkflowFiles
+  });
+}
+
+async function main() {
+  const result = await validateRegistries(parseArgs(process.argv.slice(2)));
+  if (!result.ok) {
+    for (const error of result.errors) {
+      console.error(error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Registries are consistent.");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/validate-workflow-manifest.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { validateRegistries } from "./validate-registries.mjs";
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const value = argv[index + 1];
+    if (arg === "--package-root") {
+      options.packageRoot = value;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+export async function validateWorkflowManifest(options = {}) {
+  return validateRegistries(options);
+}
+
+async function main() {
+  const result = await validateWorkflowManifest(parseArgs(process.argv.slice(2)));
+  if (!result.ok) {
+    for (const error of result.errors) {
+      console.error(error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Workflow manifest is valid.");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/version.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const skillRoot = resolve(scriptDir, "..");
+const installedPluginRoot = resolve(skillRoot, "..");
+const defaultRoot = existsSync(join(installedPluginRoot, ".codex-plugin", "plugin.json")) ? installedPluginRoot : skillRoot;
+
+function parseArgs(argv) {
+  const args = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--plugin-root") {
+      args.pluginRoot = argv[index + 1];
+      index += 1;
+    } else if (argv[index] === "--json") {
+      args.json = true;
+    }
+  }
+
+  return args;
+}
+
+async function readTextIfExists(path) {
+  if (!existsSync(path)) {
+    return "";
+  }
+  return (await readFile(path, "utf8")).trim();
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function gitCommit(root) {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--short", "HEAD"], { cwd: root });
+    return stdout.trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+function runtimeRootFor(root) {
+  return existsSync(join(root, "storewright", "scripts")) ? join(root, "storewright") : root;
+}
+
+async function stageWorkflowCapabilities(runtimeRoot) {
+  const workflowRoot = join(runtimeRoot, "workflows");
+  const stagesRoot = join(workflowRoot, "stages");
+  const specsRoot = join(workflowRoot, "stage-specs");
+  const gateSpecsRoot = join(workflowRoot, "gate-specs");
+  const capabilities = [];
+
+  if (!existsSync(stagesRoot)) {
+    return capabilities;
+  }
+
+  const stageEntries = await readdir(stagesRoot, { withFileTypes: true });
+  capabilities.push(...stageEntries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => `workflows/stages/${entry.name}`)
+    .sort());
+
+  if (existsSync(specsRoot)) {
+    const specEntries = await readdir(specsRoot, { withFileTypes: true });
+    capabilities.push(...specEntries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => `workflows/stage-specs/${entry.name}`)
+      .sort());
+  }
+
+  if (existsSync(gateSpecsRoot)) {
+    const gateSpecEntries = await readdir(gateSpecsRoot, { withFileTypes: true });
+    capabilities.push(...gateSpecEntries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => `workflows/gate-specs/${entry.name}`)
+      .sort());
+  }
+
+  return capabilities;
+}
+
+async function directoryFileCapabilities(runtimeRoot, relativeDir, extension) {
+  const dir = join(runtimeRoot, relativeDir);
+  if (!existsSync(dir)) {
+    return [];
+  }
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(extension))
+    .map((entry) => `${relativeDir}/${entry.name}`)
+    .sort();
+}
+
+async function capabilityScripts(root) {
+  const runtimeRoot = runtimeRootFor(root);
+  const scriptsRoot = join(runtimeRoot, "scripts");
+  const cliBin = join(runtimeRoot, "bin", "storewright.mjs");
+  const workflowContract = join(runtimeRoot, "workflows", "official-build.md");
+  const setupSkill = join(runtimeRoot, "skills", "storewright-setup", "SKILL.md");
+  const capabilities = existsSync(workflowContract) ? ["workflows/official-build.md"] : [];
+  const publicScripts = [
+    "audit-run-state.mjs",
+    "execute-shopify-operation.mjs",
+    "generate-image-assets-openai.mjs",
+    "generate-media-assets.mjs",
+    "inspect-media-files.mjs",
+    "install-agent-profiles.mjs",
+    "init-run-state.mjs",
+    "prepare-launch-envelope.mjs",
+    "shopify-access-preflight.mjs",
+    "upload-shopify-media.mjs",
+    "validate-agent-discovery.mjs",
+    "validate-agent-report.mjs",
+    "validate-artifact.mjs",
+    "validate-launch-envelope.mjs",
+    "validate-registries.mjs",
+    "validate-workflow-manifest.mjs",
+    "version.mjs"
+  ];
+  const publicSchemas = [
+    "shopify-operation-request.schema.json"
+  ];
+
+  return [
+    ...capabilities,
+    ...(await directoryFileCapabilities(runtimeRoot, "contracts", ".json")),
+    ...publicSchemas
+      .filter((schema) => existsSync(join(runtimeRoot, "schemas", schema)))
+      .map((schema) => `schemas/${schema}`),
+    ...(existsSync(setupSkill) ? ["skills/storewright-setup/SKILL.md"] : []),
+    ...(await stageWorkflowCapabilities(runtimeRoot)),
+    ...(existsSync(cliBin) ? ["bin/storewright.mjs"] : []),
+    ...publicScripts.filter((script) => existsSync(join(scriptsRoot, script)))
+  ];
+}
+
+export async function getVersionInfo({ pluginRoot: explicitPluginRoot = defaultRoot } = {}) {
+  const root = resolve(explicitPluginRoot);
+  const runtimeRoot = runtimeRootFor(root);
+  const manifestPath = join(root, ".codex-plugin", "plugin.json");
+  const packageJsonPath = join(runtimeRoot, "package.json");
+  const manifest = existsSync(manifestPath) ? await readJson(manifestPath) : null;
+  const packageJson = existsSync(packageJsonPath) ? await readJson(packageJsonPath) : null;
+  const pluginVersion = await readTextIfExists(existsSync(manifestPath) ? join(root, "VERSION") : join(runtimeRoot, "VERSION"));
+  const skillVersion = existsSync(manifestPath) ? await readTextIfExists(join(runtimeRoot, "VERSION")) : "";
+
+  return {
+    name: manifest?.name ?? packageJson?.name ?? "storewright",
+    displayName: manifest?.interface?.displayName ?? (packageJson?.name === "@storewright/cli" ? "Storewright CLI" : packageJson?.name ?? "Storewright"),
+    manifestVersion: manifest?.version ?? "",
+    packageVersion: packageJson?.version ?? "",
+    pluginVersion,
+    skillVersion,
+    gitCommit: await gitCommit(root),
+    capabilities: await capabilityScripts(root)
+  };
+}
+
+function textOutput(info) {
+  return [
+    `${info.displayName} (${info.name})`,
+    `manifestVersion: ${info.manifestVersion}`,
+    `pluginVersion: ${info.pluginVersion || "missing"}`,
+    `skillVersion: ${info.skillVersion || "missing"}`,
+    `gitCommit: ${info.gitCommit}`,
+    "capabilities:",
+    ...info.capabilities.map((capability) => `- ${capability}`)
+  ].join("\n");
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const info = await getVersionInfo({ pluginRoot: args.pluginRoot });
+    console.log(args.json ? JSON.stringify(info, null, 2) : textOutput(info));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}