@storewright/cli 0.14.0

package/lib/cli/storewright-cli.mjs

@@ -0,0 +1,259 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+const cliDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(cliDir, "..", "..");
+const defaultMarketplaceSource = "git@github.com:HughLee824/storewright.git";
+const defaultMarketplaceName = "storewright";
+
+const scriptCommandMap = new Map([
+  ["audit-run-state.mjs", ["run", "audit"]],
+  ["execute-shopify-operation.mjs", ["shopify", "operation", "execute"]],
+  ["generate-image-assets-openai.mjs", ["media", "generate-openai"]],
+  ["generate-media-assets.mjs", ["media", "generate"]],
+  ["init-run-state.mjs", ["run", "init"]],
+  ["inspect-media-files.mjs", ["media", "inspect"]],
+  ["prepare-launch-envelope.mjs", ["launch-envelope", "prepare"]],
+  ["shopify-access-preflight.mjs", ["shopify", "access-preflight"]],
+  ["upload-shopify-media.mjs", ["media", "upload"]],
+  ["validate-agent-report.mjs", ["agent-report", "validate"]],
+  ["validate-artifact.mjs", ["artifact", "validate"]],
+  ["validate-launch-envelope.mjs", ["launch-envelope", "validate"]],
+  ["validate-registries.mjs", ["registries", "validate"]],
+  ["validate-workflow-manifest.mjs", ["workflow-manifest", "validate"]],
+  ["version.mjs", ["version"]]
+]);
+
+const commandScriptMap = new Map(Array.from(scriptCommandMap.entries()).map(([script, command]) => [command.join(" "), script]));
+
+export function cliCommandForScript(scriptName) {
+  return scriptCommandMap.get(scriptName);
+}
+
+function parseTomlName(source) {
+  return source.match(/^name = "([^"]+)"/m)?.[1] ?? null;
+}
+
+async function codexExec(args, { env = process.env, label = "codex" } = {}) {
+  try {
+    const result = await execFileAsync("codex", args, {
+      env,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return result;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error("Codex CLI was not found on PATH. Install Codex CLI before running storewright codex install.");
+    }
+    const stderr = String(error.stderr ?? "").trim();
+    const stdout = String(error.stdout ?? "").trim();
+    const detail = [stderr, stdout].filter(Boolean).join("\n");
+    throw new Error(`${label} failed${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+function parseJsonOutput(stdout, label) {
+  const text = stdout.trim();
+  try {
+    return JSON.parse(text);
+  } catch {
+    for (let index = text.lastIndexOf("{"); index >= 0; index = text.lastIndexOf("{", index - 1)) {
+      try {
+        return JSON.parse(text.slice(index));
+      } catch {
+        // Keep scanning earlier object starts until one parses.
+      }
+    }
+  }
+  throw new Error(`${label} did not return valid JSON.`);
+}
+
+function findPluginRoot(value) {
+  if (typeof value === "string") {
+    return existsSync(join(value, ".codex-plugin", "plugin.json")) ? value : null;
+  }
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (/path|root/i.test(key) && typeof child === "string") {
+      const maybeRoot = findPluginRoot(child);
+      if (maybeRoot) return maybeRoot;
+    }
+  }
+  for (const child of Object.values(value)) {
+    const maybeRoot = findPluginRoot(child);
+    if (maybeRoot) return maybeRoot;
+  }
+  return null;
+}
+
+async function readPluginManifest(pluginRoot) {
+  return JSON.parse(await readFile(join(pluginRoot, ".codex-plugin", "plugin.json"), "utf8"));
+}
+
+async function tomlFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".toml"))
+    .map((entry) => join(dir, entry.name))
+    .sort();
+}
+
+async function installProfilesFromPlugin({ pluginRoot, codexHome }) {
+  const sourceDir = join(pluginRoot, "storewright", "scaffolds", "codex-agents");
+  if (!existsSync(sourceDir)) {
+    throw new Error(`Installed Storewright plugin is missing agent scaffolds: ${sourceDir}`);
+  }
+
+  const targetDir = join(codexHome, "agents");
+  await mkdir(targetDir, { recursive: true });
+  const installedProfiles = [];
+  const installedFiles = [];
+  const skippedFiles = [];
+
+  for (const sourcePath of await tomlFiles(sourceDir)) {
+    const source = await readFile(sourcePath, "utf8");
+    const profileName = parseTomlName(source);
+    if (!profileName) {
+      throw new Error(`Missing name in ${sourcePath}`);
+    }
+    const targetPath = join(targetDir, basename(sourcePath));
+    if (existsSync(targetPath)) {
+      const existingName = parseTomlName(await readFile(targetPath, "utf8"));
+      if (!existingName || !existingName.startsWith("storewright-")) {
+        skippedFiles.push(targetPath);
+        continue;
+      }
+    }
+    await copyFile(sourcePath, targetPath);
+    installedProfiles.push(profileName);
+    installedFiles.push(targetPath);
+  }
+
+  return { targetDir, installedProfiles, installedFiles, skippedFiles };
+}
+
+function normalizeInstallOptions(options = {}) {
+  const source = options.source ?? "git";
+  const marketplaceName = options.marketplace ?? defaultMarketplaceName;
+  if (!["git", "local", "marketplace"].includes(source)) {
+    throw new Error("--source must be one of git, local, or marketplace");
+  }
+  if (source === "local" && !options.marketplaceRoot) {
+    throw new Error("--marketplace-root is required when --source local");
+  }
+  return {
+    source,
+    marketplaceName,
+    marketplaceRoot: options.marketplaceRoot,
+    marketplaceSource: options.marketplaceSource ?? defaultMarketplaceSource,
+    codexHome: options.codexHome ?? join(homedir(), ".codex"),
+    env: options.env ?? process.env
+  };
+}
+
+export async function installCodexStorewright(options = {}) {
+  const normalized = normalizeInstallOptions(options);
+  await codexExec(["--help"], { env: normalized.env, label: "codex --help" });
+
+  const commandResults = [];
+  if (normalized.source === "git") {
+    const addMarketplace = await codexExec(["plugin", "marketplace", "add", normalized.marketplaceSource, "--json"], {
+      env: normalized.env,
+      label: "codex plugin marketplace add"
+    });
+    commandResults.push({ command: "codex plugin marketplace add", stdout: addMarketplace.stdout.trim() });
+  } else if (normalized.source === "local") {
+    const addMarketplace = await codexExec(["plugin", "marketplace", "add", normalized.marketplaceRoot, "--json"], {
+      env: normalized.env,
+      label: "codex plugin marketplace add"
+    });
+    commandResults.push({ command: "codex plugin marketplace add", stdout: addMarketplace.stdout.trim() });
+  }
+
+  const selector = `storewright@${normalized.marketplaceName}`;
+  const addPlugin = await codexExec(["plugin", "add", selector, "--json"], {
+    env: normalized.env,
+    label: "codex plugin add"
+  });
+  commandResults.push({ command: "codex plugin add", stdout: addPlugin.stdout.trim() });
+  const pluginInstall = parseJsonOutput(addPlugin.stdout, "codex plugin add");
+  const pluginRoot = findPluginRoot(pluginInstall);
+  if (!pluginRoot) {
+    throw new Error("codex plugin add did not report an installed Storewright plugin path.");
+  }
+
+  const manifest = await readPluginManifest(pluginRoot);
+  const profileInstall = await installProfilesFromPlugin({ pluginRoot, codexHome: normalized.codexHome });
+  const report = {
+    schemaVersion: "1.0.0",
+    installationStatus: "valid",
+    runtimeStatus: "requires_new_session",
+    runtimeProbeRequired: true,
+    sourceMode: normalized.source,
+    marketplaceName: normalized.marketplaceName,
+    marketplaceSource: normalized.source === "git" ? normalized.marketplaceSource : undefined,
+    marketplaceRoot: normalized.source === "local" ? normalized.marketplaceRoot : undefined,
+    pluginRoot,
+    pluginVersion: manifest.version ?? "unknown",
+    profileTargetDir: profileInstall.targetDir,
+    installedProfiles: profileInstall.installedProfiles,
+    installedFiles: profileInstall.installedFiles,
+    skippedFiles: profileInstall.skippedFiles,
+    commands: commandResults,
+    nextStep: "Start a new Codex session so Storewright agent profiles are loaded into the runtime."
+  };
+
+  const reportDir = join(normalized.codexHome, "storewright");
+  await mkdir(reportDir, { recursive: true });
+  await writeFile(join(reportDir, "codex-install-report.json"), `${JSON.stringify(report, null, 2)}\n`);
+  return report;
+}
+
+export function parseCodexInstallArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const value = argv[index + 1];
+    if (arg === "--source") {
+      options.source = value;
+      index += 1;
+    } else if (arg === "--marketplace-root") {
+      options.marketplaceRoot = value;
+      index += 1;
+    } else if (arg === "--marketplace") {
+      options.marketplace = value;
+      index += 1;
+    } else if (arg === "--codex-home") {
+      options.codexHome = value;
+      index += 1;
+    } else if (arg === "--marketplace-source") {
+      options.marketplaceSource = value;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+export function resolveScriptForCommand(argv) {
+  for (let length = Math.min(3, argv.length); length >= 1; length -= 1) {
+    const key = argv.slice(0, length).join(" ");
+    const script = commandScriptMap.get(key);
+    if (script) {
+      return { script, consumed: length, passthrough: argv.slice(length) };
+    }
+  }
+  return null;
+}
+
+export function scriptPathForCommand(script) {
+  return join(packageRoot, "scripts", script);
+}

package/lib/internal/launch-envelope.mjs

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, normalize } from "node:path";
+
+export async function sha256File(path) {
+  const bytes = await readFile(path);
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(sortJson(value), null, 2)}\n`;
+}
+
+function sha256Text(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+export function canonicalLaunchEnvelopeSha256(envelope) {
+  const canonicalEnvelope = { ...envelope };
+  delete canonicalEnvelope.launchEnvelopeSha256;
+  return sha256Text(stableJson(canonicalEnvelope));
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, sortJson(child)])
+    );
+  }
+  return value;
+}
+
+function normalizedRelativePath(path) {
+  if (!path || typeof path !== "string") return null;
+  if (path.startsWith("/") || path.includes("\\") || path.includes("\0")) return null;
+  const normalized = normalize(path);
+  if (normalized === "." || normalized.startsWith("..") || normalized.includes("../")) return null;
+  return normalized;
+}
+
+function assertSafePathSegment(errors, label, value) {
+  if (!value || typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value)) {
+    errors.push(`${label} must be a single safe path segment`);
+  }
+}
+
+function requestedRuntimePolicyErrors(policy) {
+  const errors = [];
+  if (!policy || typeof policy !== "object") {
+    return ["requestedRuntimePolicy is required"];
+  }
+  if (policy.kind === "permissions-profile") {
+    if (!policy.profile) errors.push("requestedRuntimePolicy.profile is required");
+    if (Object.hasOwn(policy, "sandboxMode")) {
+      errors.push("requestedRuntimePolicy permissions-profile and sandboxMode are mutually exclusive");
+    }
+  } else if (policy.kind === "legacy-sandbox") {
+    if (!policy.sandboxMode) errors.push("requestedRuntimePolicy.sandboxMode is required");
+    if (Object.hasOwn(policy, "profile")) {
+      errors.push("requestedRuntimePolicy legacy-sandbox and profile are mutually exclusive");
+    }
+  } else {
+    errors.push("requestedRuntimePolicy.kind must be permissions-profile or legacy-sandbox");
+  }
+  return errors;
+}
+
+function assertSafePath(errors, label, path) {
+  const normalized = normalizedRelativePath(path);
+  if (!normalized) {
+    errors.push(`${label} has unsafe path: ${path}`);
+  }
+  return normalized;
+}
+
+export async function createLaunchEnvelope({
+  packageRoot,
+  runDir,
+  runId,
+  stageId,
+  stageName,
+  attemptId,
+  ownerProfile,
+  runtimeAgentType,
+  packetPath,
+  specPath,
+  gateSpecPath,
+  actionPolicyRef,
+  requestedRuntimePolicy,
+  runtimeToolSnapshot = [],
+  effectiveAllowedActions = [],
+  resolvedInputs = [],
+  declaredOutputs = []
+}) {
+  const attemptPrefix = `stages/${stageId}/attempts/${attemptId}`;
+  const envelope = {
+    schemaVersion: "1.0.0",
+    run: { id: runId },
+    stage: { id: stageId, name: stageName },
+    attempt: { id: attemptId },
+    launchEnvelopePath: `${attemptPrefix}/control/launch-envelope.json`,
+    ownerProfile,
+    runtimeAgentType,
+    packetPath,
+    specPath,
+    gateSpecPath,
+    actionPolicyRef,
+    requestedRuntimePolicy,
+    runtimeToolSnapshot,
+    effectiveAllowedActions: [...effectiveAllowedActions].sort(),
+    resolvedInputs,
+    declaredOutputs,
+    pathConstraints: {
+      controlPrefix: `${attemptPrefix}/control/`,
+      workPrefix: `${attemptPrefix}/work/`
+    }
+  };
+
+  const validation = await validateLaunchEnvelope({ packageRoot, runDir, envelope });
+  if (!validation.ok) {
+    throw new Error(validation.errors.join("\n"));
+  }
+
+  const envelopePath = join(runDir, envelope.launchEnvelopePath);
+  await mkdir(dirname(envelopePath), { recursive: true });
+  await mkdir(join(runDir, attemptPrefix, "work", "outputs"), { recursive: true });
+  envelope.launchEnvelopeSha256 = canonicalLaunchEnvelopeSha256(envelope);
+  await writeFile(envelopePath, stableJson(envelope));
+  return envelope;
+}
+
+export async function validateLaunchEnvelope({ packageRoot, runDir, envelope }) {
+  const errors = [];
+  errors.push(...requestedRuntimePolicyErrors(envelope.requestedRuntimePolicy));
+  assertSafePathSegment(errors, "stage.id", envelope.stage?.id);
+  assertSafePathSegment(errors, "attempt.id", envelope.attempt?.id);
+
+  for (const [label, path] of [
+    ["launchEnvelopePath", envelope.launchEnvelopePath],
+    ["packetPath", envelope.packetPath],
+    ["specPath", envelope.specPath],
+    ["gateSpecPath", envelope.gateSpecPath]
+  ]) {
+    assertSafePath(errors, label, path);
+  }
+
+  for (const [label, path] of [
+    ["packetPath", envelope.packetPath],
+    ["specPath", envelope.specPath],
+    ["gateSpecPath", envelope.gateSpecPath]
+  ]) {
+    if (path && !existsSync(join(packageRoot, path))) {
+      errors.push(`${label} does not exist: ${path}`);
+    }
+  }
+
+  const attemptPrefix = `stages/${envelope.stage?.id}/attempts/${envelope.attempt?.id}`;
+  const controlPrefix = `${attemptPrefix}/control/`;
+  const workPrefix = `${attemptPrefix}/work/`;
+  if (envelope.launchEnvelopePath !== `${controlPrefix}launch-envelope.json`) {
+    errors.push("launchEnvelopePath must be in the attempt control plane");
+  }
+
+  for (const input of envelope.resolvedInputs ?? []) {
+    const path = assertSafePath(errors, `resolvedInputs.${input.artifactId}`, input.path);
+    if (path && !path.includes("/work/outputs/")) {
+      errors.push(`resolved input must point at accepted work/outputs artifact: ${input.path}`);
+    }
+    if (path && runDir && !existsSync(join(runDir, path))) {
+      errors.push(`resolved input does not exist in run dir: ${input.path}`);
+    }
+    if (path && runDir && existsSync(join(runDir, path))) {
+      const actualSha256 = await sha256File(join(runDir, path));
+      if (input.sha256 !== actualSha256) {
+        errors.push(`resolved input sha256 does not match file contents: ${input.path}`);
+      }
+    }
+  }
+
+  for (const output of envelope.declaredOutputs ?? []) {
+    const path = assertSafePath(errors, `declaredOutputs.${output.artifactId}`, output.path);
+    if (path && !path.startsWith(`${workPrefix}outputs/`)) {
+      errors.push(`declared output must stay under current attempt work/outputs: ${output.path}`);
+    }
+  }
+
+  const uniqueActions = new Set(envelope.effectiveAllowedActions ?? []);
+  if (uniqueActions.size !== (envelope.effectiveAllowedActions ?? []).length) {
+    errors.push("effectiveAllowedActions must not contain duplicates");
+  }
+  if (
+    Object.hasOwn(envelope, "launchEnvelopeSha256") &&
+    envelope.launchEnvelopeSha256 !== canonicalLaunchEnvelopeSha256(envelope)
+  ) {
+    errors.push("launchEnvelopeSha256 does not match canonical envelope contents");
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function validateAgentReportAgainstEnvelope({ envelope, report }) {
+  const errors = [];
+  if (report.launchEnvelopeSha256 !== envelope.launchEnvelopeSha256) {
+    errors.push("agent report launchEnvelopeSha256 must match envelope");
+  }
+  if (!sameJson(report.inputArtifacts, envelope.resolvedInputs)) {
+    errors.push("agent report inputArtifacts must exactly match envelope resolvedInputs");
+  }
+  if (!sameJson(report.effectiveAllowedActions, envelope.effectiveAllowedActions)) {
+    errors.push("agent report effectiveAllowedActions must exactly match envelope effectiveAllowedActions");
+  }
+  return { ok: errors.length === 0, errors };
+}

package/lib/internal/multi-agent-contracts.mjs

@@ -0,0 +1,137 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+function executorKey(executor) {
+  return `${executor.server}:${executor.tool}`;
+}
+
+function includesAll(values, required = []) {
+  const valueSet = new Set(values ?? []);
+  return required.every((value) => valueSet.has(value));
+}
+
+export function computeActionExecutionPlan({
+  actionRegistry,
+  requestedActions = Object.keys(actionRegistry.actions ?? {}),
+  availableExecutors = [],
+  grantedScopes = [],
+  satisfiedPreconditions = []
+}) {
+  const availableExecutorKeys = new Set(availableExecutors.map(executorKey));
+  const executable = [];
+  const blockedActions = [];
+
+  for (const actionId of requestedActions) {
+    const action = actionRegistry.actions?.[actionId];
+    if (!action) {
+      blockedActions.push({ actionId, reason: "unknown-action" });
+      continue;
+    }
+    if (!availableExecutorKeys.has(executorKey(action.executor))) {
+      blockedActions.push({ actionId, reason: "executor-unavailable", executor: action.executor });
+      continue;
+    }
+    if (!includesAll(grantedScopes, action.requiredScopes)) {
+      const granted = new Set(grantedScopes);
+      blockedActions.push({
+        actionId,
+        reason: "missing-scopes",
+        missingScopes: (action.requiredScopes ?? []).filter((scope) => !granted.has(scope))
+      });
+      continue;
+    }
+    if (!includesAll(satisfiedPreconditions, action.requiredPreconditions)) {
+      const satisfied = new Set(satisfiedPreconditions);
+      blockedActions.push({
+        actionId,
+        reason: "missing-preconditions",
+        missingPreconditions: (action.requiredPreconditions ?? []).filter((precondition) => !satisfied.has(precondition))
+      });
+      continue;
+    }
+    executable.push(actionId);
+  }
+
+  return { executableActions: executable.sort(), blockedActions };
+}
+
+export function computeExecutableActions(options) {
+  return computeActionExecutionPlan(options).executableActions;
+}
+
+export function computeEffectiveAllowedActions({
+  capabilityCeiling = [],
+  stageRequestedActions = [],
+  workflowActionPolicy = [],
+  executableActions = []
+}) {
+  const ceiling = new Set(capabilityCeiling);
+  const policy = new Set(workflowActionPolicy);
+  const executable = new Set(executableActions);
+  return [...new Set(stageRequestedActions)]
+    .filter((actionId) => ceiling.has(actionId))
+    .filter((actionId) => policy.has(actionId))
+    .filter((actionId) => executable.has(actionId))
+    .sort();
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function hasUnsafePath(path) {
+  return !path || path.includes("..") || path.startsWith("/") || path.includes("\\");
+}
+
+export async function validateRegistryConsistency({
+  root,
+  workflowManifestPath,
+  capabilityRegistryPath,
+  actionRegistryPath,
+  requireWorkflowFiles = true
+}) {
+  const errors = [];
+  const manifest = await readJson(workflowManifestPath);
+  const capabilityRegistry = await readJson(capabilityRegistryPath);
+  const actionRegistry = await readJson(actionRegistryPath);
+  const actionIds = new Set(Object.keys(actionRegistry.actions ?? {}));
+  const profileNames = new Set(Object.keys(capabilityRegistry.profiles ?? {}));
+
+  for (const stage of manifest.stages ?? []) {
+    for (const key of ["packet", "spec", "gateSpec"]) {
+      if (hasUnsafePath(stage[key])) {
+        errors.push(`${stage.id}.${key} is unsafe: ${stage[key]}`);
+      } else if (requireWorkflowFiles && !existsSync(join(root, stage[key]))) {
+        errors.push(`${stage.id}.${key} does not exist: ${stage[key]}`);
+      }
+    }
+    if (!profileNames.has(stage.runtimeAgentType)) {
+      errors.push(`${stage.id}.runtimeAgentType is not registered: ${stage.runtimeAgentType}`);
+    }
+    for (const forbiddenKey of ["inputs", "outputs", "artifactSchemas", "stopConditions"]) {
+      if (Object.hasOwn(stage, forbiddenKey)) {
+        errors.push(`${stage.id} manifest entry must not own ${forbiddenKey}`);
+      }
+    }
+  }
+
+  for (const [profileName, profile] of Object.entries(capabilityRegistry.profiles ?? {})) {
+    for (const actionId of profile.allowedActions ?? []) {
+      if (!actionIds.has(actionId)) {
+        errors.push(`${profileName} references unknown action ${actionId}`);
+      }
+    }
+  }
+
+  for (const [actionId, action] of Object.entries(actionRegistry.actions ?? {})) {
+    if (action.executor?.tool === actionId) {
+      errors.push(`${actionId} executor tool must not equal business action id`);
+    }
+    if (!Array.isArray(action.requiredScopes)) {
+      errors.push(`${actionId} requiredScopes must be an array`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}