@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/scripts/cms-fallback.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+'use strict';
+
+// CMS-fallback plumbing for plugin capabilities, as one deterministic command:
+//
+//   node scripts/cms-fallback.js digest     --project-dir <dir>
+//       Current resolution-input digest and which artifact (if any) is stale.
+//   node scripts/cms-fallback.js stamp-plan --project-dir <dir> --plan mapping|setup
+//       Copy inputs.cmsFallbackDigest into mapping/mapping-plan.json (from
+//       discovery/plugin-coverage.json) or setup/setup-plan.json (from the mapping plan).
+//   node scripts/cms-fallback.js guard      --project-dir <dir> [--capability <id>]
+//       The write-time guard: which eligible capabilities may have CMS records written.
+//       Exit 2 when the named capability (or, without --capability, any capability whose coverage
+//       row still claims an approved CMS plan) is refused.
+//
+// Optional on every command: --plugins-root <dir> --target-knowledge-root <dir> (fixture trees).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  checkCmsFallbackFreshness,
+  cmsFallbackWriteGuard,
+  stampPlanDigest,
+} = require('../lib/plugin-cms-fallback.js');
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      args._.push(token);
+      continue;
+    }
+    args[token.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function readDecisions(projectDir) {
+  try {
+    return readJson(path.join(projectDir, 'orchestration', 'decisions.json'));
+  } catch {
+    return {};
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  if (!command || !args.projectDir) {
+    console.error('Usage: node scripts/cms-fallback.js digest|stamp-plan|guard --project-dir <dir> [--plan mapping|setup] [--capability <id>]');
+    process.exit(1);
+  }
+  const projectDir = path.resolve(args.projectDir);
+  const overrides = {
+    pluginsRoot: args.pluginsRoot ? path.resolve(args.pluginsRoot) : undefined,
+    targetKnowledgeRoot: args.targetKnowledgeRoot ? path.resolve(args.targetKnowledgeRoot) : undefined,
+  };
+
+  if (command === 'digest') {
+    const result = checkCmsFallbackFreshness(projectDir, { decisions: readDecisions(projectDir), ...overrides });
+    console.log(JSON.stringify({ ok: true, ...(result || { digest: null, stale: null, reason: 'no plugin coverage' }) }, null, 2));
+    return;
+  }
+  if (command === 'stamp-plan') {
+    console.log(JSON.stringify({ ok: true, ...stampPlanDigest(projectDir, args.plan) }, null, 2));
+    return;
+  }
+  if (command === 'guard') {
+    const result = cmsFallbackWriteGuard(projectDir, { ...overrides, attempted: args.capability ? [args.capability] : null });
+    const refused = result.refusals;
+    console.log(JSON.stringify({ ok: refused.length === 0, ...result }, null, 2));
+    if (refused.length > 0) process.exitCode = 2;
+    return;
+  }
+  throw new Error(`unknown command: ${command}`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/skills/wix-replatform/scripts/discovered-census.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const {
+  buildCensus,
+  rolloutScan
+} = require('../lib/discovered-census.js');
+async function main(args = process.argv.slice(2)) {
+  const [command, dir] = args;
+  if (!['build', 'rollout-scan'].includes(command) || !dir || args.length !== 2) throw new Error('Usage: discovered-census.js build <projectDir> | rollout-scan <migrations-root>');
+  const result = command === 'build' ? await buildCensus(path.resolve(dir)) : await rolloutScan(path.resolve(dir));
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}
+if (require.main === module) main().catch(error => {
+  process.stderr.write(`${JSON.stringify({
+    ok: false,
+    code: error.code || 'census_build_failed',
+    message: error.message
+  })}\n`);
+  process.exitCode = 1;
+});
+module.exports = {
+  main
+};

package/skills/wix-replatform/scripts/discovered-set-status.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const {
+  buildDiscoveredSetStatus,
+  resolveDiscoveredSet
+} = require('../lib/discovered-set-status.js');
+async function main() {
+  const [command, project, ...rest] = process.argv.slice(2);
+  if (!project || !['build', 'resolve'].includes(command)) throw new Error('Usage: discovered-set-status.js build|resolve <projectDir> [--census-id <id> --by merchant|cutover-operator --evidence <short non-record evidence>]');
+  const flags = {};
+  for (let i = 0; i < rest.length; i += 2) flags[rest[i]] = rest[i + 1];
+  const projectDir = path.resolve(project);
+  const result = command === 'build' ? await buildDiscoveredSetStatus(projectDir) : await resolveDiscoveredSet(projectDir, {
+    censusId: flags['--census-id'],
+    by: flags['--by'],
+    evidence: flags['--evidence']
+  });
+  console.log(JSON.stringify({
+    ok: true,
+    status: result
+  }, null, 2));
+}
+main().catch(error => {
+  console.error(JSON.stringify({
+    ok: false,
+    code: error.code || error.message,
+    staleInputs: error.staleInputs,
+    errors: error.errors
+  }));
+  process.exitCode = 1;
+});

package/skills/wix-replatform/scripts/entity-qa-attestation.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+'use strict';
+
+// The deterministic writer half of the entity-QA attestation gate. The QA
+// subagent does the actual entity-by-entity pass (`rp-execute-import/SKILL.md`'s "Entity-by-
+// entity QA" section) and hands its per-entity results to this script as a plain JSON file;
+// this script never re-derives or copies counts out of the completion report on its own -- it
+// only computes the report digest, resolves the independent mapped-entity coverage source
+// (`mapping/mapping-plan.json` or, for quick mode, `quick-mode/plan.json`), and writes the
+// attestation atomically, but ONLY if it validates. A count mismatch (or any other gate
+// failure) is printed as a QA finding and the script exits non-zero without writing anything --
+// it must never overwrite a previously-valid attestation with a broken one.
+//
+// Usage:
+//   node scripts/entity-qa-attestation.js <projectDir> --entities-file <path> [--verified-by <label>]
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { BACKEND_COMPLETION_FILE, readMappedEntities } = require('../lib/migration-completion.js');
+const { hashArtifact } = require('../lib/artifact-freshness.js');
+const { ENTITY_QA_ATTESTATION_FILE, SCHEMA_VERSION, validateEntityQaAttestation } = require('../lib/entity-qa-attestation.js');
+const { writeJsonAtomic } = require('../lib/orchestration-state.js');
+
+function usage() {
+  console.error(`Usage:
+  node skills/wix-replatform/scripts/entity-qa-attestation.js <projectDir> --entities-file <path> [--verified-by <label>]
+
+Reads the QA subagent's per-entity results from --entities-file (a JSON array; full-mode rows
+carry the ten completion-report fields, quick-mode rows carry imported/skipped), computes the
+digest of <projectDir>/execution/completion-report.json itself, resolves the independent
+mapped-entity coverage source by mode, and writes <projectDir>/execution/qa/entity-qa-attestation.json
+ONLY if the result validates. A count mismatch or any other gate failure is printed as a
+finding and the script exits non-zero without writing the file.
+`);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = { entitiesFile: null, verifiedBy: 'qa-subagent' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--entities-file') {
+      options.entitiesFile = argv[i + 1];
+      i += 1;
+    } else if (arg === '--verified-by') {
+      options.verifiedBy = argv[i + 1];
+      i += 1;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { projectDir: positional[0], ...options };
+}
+
+function readJsonFile(filePath, label) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new Error(`${label} not found at ${filePath}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${label} at ${filePath} is not valid JSON: ${error.message}`);
+  }
+}
+
+function printFindings(result) {
+  if (result.entities && result.entities.length) {
+    for (const entry of result.entities) {
+      console.error(`${entry.entity}/${entry.subtype}: ${entry.reasons.join(', ')}`);
+    }
+  } else {
+    for (const reason of result.reasons) {
+      console.error(reason);
+    }
+  }
+}
+
+async function main() {
+  const { projectDir: projectDirArg, entitiesFile, verifiedBy } = parseArgs(process.argv.slice(2));
+  if (!projectDirArg || !entitiesFile) {
+    usage();
+    process.exit(1);
+    return;
+  }
+  const projectDir = path.resolve(projectDirArg);
+
+  const report = readJsonFile(path.join(projectDir, BACKEND_COMPLETION_FILE), 'completion report');
+  const entities = readJsonFile(path.resolve(entitiesFile), 'entities file');
+  if (!Array.isArray(entities)) {
+    throw new Error(`--entities-file must contain a JSON array of per-entity rows: ${entitiesFile}`);
+  }
+
+  const managementImportMode = report.managementImportMode === 'quick' ? 'quick' : 'full';
+  const mappedEntities = await readMappedEntities(projectDir, managementImportMode);
+  const completionReportDigest = hashArtifact(projectDir, BACKEND_COMPLETION_FILE);
+
+  const attestation = {
+    schemaVersion: SCHEMA_VERSION,
+    completionReportDigest,
+    verifiedAt: new Date().toISOString(),
+    verifiedBy,
+    entities,
+  };
+
+  const result = validateEntityQaAttestation({
+    attestation,
+    report,
+    reportDigest: completionReportDigest,
+    mappedEntities,
+  });
+
+  if (!result.ok) {
+    console.error(JSON.stringify({ ok: false, qaStatus: result.qaStatus, projectDir }, null, 2));
+    printFindings(result);
+    process.exit(1);
+    return;
+  }
+
+  const outputPath = path.join(projectDir, ENTITY_QA_ATTESTATION_FILE);
+  await writeJsonAtomic(outputPath, attestation);
+  console.log(JSON.stringify({ ok: true, outputPath, qaStatus: result.qaStatus }, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});