capix-code 1.3.0

package/scripts/resolve-version.mjs

@@ -0,0 +1,126 @@
+/**
+ * Resolve a requested version ("latest", empty, or an explicit tag) to an
+ * immutable vMAJOR.MINOR.PATCH tag.
+ *
+ * "latest" is permitted ONLY by resolving it to a concrete immutable version
+ * before any download — never by blindly trusting mutable content. Resolution
+ * sources, in priority order:
+ *
+ *   1. CAPIX_STABLE_VERSION env (deterministic, offline, release-pinned)
+ *   2. a materialized manifest's stableVersion (single source of truth)
+ *   3. the GitHub releases API /releases/latest tag_name (--allow-network only)
+ *
+ * If none resolves, the script fails closed (exit 2) so the installer never
+ * proceeds with an unbounded/mutable version.
+ *
+ * Usage:
+ *   node scripts/resolve-version.mjs [latest|<tag>] [--manifest manifest/release-manifest.json] [--allow-network]
+ *
+ * Prints the resolved immutable tag to stdout.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const SEMVER_TAG = /^v\d+\.\d+\.\d+$/;
+
+/**
+ * Resolve a version request. Pure (no IO except the optional fetch passed in)
+ * so it is unit-testable without a network.
+ *
+ * @param {string|null} request   "latest", "" or null
+ * @param {object} ctx
+ * @param {string|undefined} ctx.envStable  CAPIX_STABLE_VERSION value
+ * @param {object|undefined} ctx.manifest   parsed manifest with stableVersion
+ * @param {(() => Promise<string|null>)|undefined} ctx.fetchLatestTag  network resolver
+ * @returns {{tag:string, source:string}}
+ */
+export function resolveVersion(request, ctx) {
+  const requested = (request ?? '').trim();
+  // An explicit immutable tag is always accepted as-is.
+  if (requested && requested !== 'latest') {
+    if (!SEMVER_TAG.test(requested)) {
+      throw new Error(`invalid version '${requested}' (expected vMAJOR.MINOR.PATCH)`);
+    }
+    return { tag: requested, source: 'explicit' };
+  }
+  // latest / empty → resolve to an immutable tag.
+  if (ctx.envStable) {
+    if (!SEMVER_TAG.test(ctx.envStable)) {
+      throw new Error(`CAPIX_STABLE_VERSION is not a vMAJOR.MINOR.PATCH tag: '${ctx.envStable}'`);
+    }
+    return { tag: ctx.envStable, source: 'env' };
+  }
+  if (
+    ctx.manifest &&
+    typeof ctx.manifest.stableVersion === 'string' &&
+    SEMVER_TAG.test(ctx.manifest.stableVersion)
+  ) {
+    return { tag: ctx.manifest.stableVersion, source: 'manifest' };
+  }
+  // Network resolver is invoked lazily by the caller (kept out of the pure
+  // path so tests never touch the network).
+  return null; // signals "caller may try network, else fail closed"
+}
+
+/** Read a manifest file and return its parsed object, or null if unreadable. */
+export function loadManifest(path) {
+  if (!path) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** GitHub releases API resolver. Returns the latest tag_name or null. */
+async function githubLatest(repo) {
+  try {
+    const res = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {
+      headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'capix-code-installer' },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const tag = body?.tag_name;
+    return typeof tag === 'string' && SEMVER_TAG.test(tag) ? tag : null;
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const request = argv.find((a) => !a.startsWith('--')) ?? '';
+  const manifestPath = argv[argv.indexOf('--manifest') + 1];
+  const allowNetwork = argv.includes('--allow-network');
+  const repo = process.env.CAPIX_RELEASE_REPO ?? 'CapIX-Protocol/Capix-Code';
+
+  const ctx = {
+    envStable: process.env.CAPIX_STABLE_VERSION?.trim() || undefined,
+    manifest: loadManifest(manifestPath),
+  };
+  const resolved = resolveVersion(request, ctx);
+  if (resolved) {
+    process.stdout.write(resolved.tag);
+    process.exit(0);
+  }
+  if (allowNetwork) {
+    const tag = await githubLatest(repo);
+    if (tag) {
+      process.stdout.write(tag);
+      process.exit(0);
+    }
+  }
+  console.error(
+    `ERROR: cannot resolve '${request || 'latest'}' to an immutable version. ` +
+      `Set CAPIX_STABLE_VERSION (e.g. v1.2.3) or pass --manifest <path> [--allow-network].`
+  );
+  process.exit(2);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main().catch((err) => {
+    console.error(err?.message ? `ERROR: ${err.message}` : String(err));
+    process.exit(2);
+  });
+}

package/scripts/validate-manifest.mjs

@@ -0,0 +1,167 @@
+/**
+ * Release manifest validator.
+ *
+ * Guarantees that a production release-manifest.json cannot ship with
+ * unmaterialized TEMPLATE placeholders, zero-size artifacts, non-HTTPS URLs,
+ * or missing/invalid checksums. A manifest that fails any check is rejected
+ * with a concrete, actionable error — it must never be silently published.
+ *
+ * Usage:
+ *   node scripts/validate-manifest.mjs <manifest.json> [--strict]
+ *
+ * Exit 0 = valid, 1 = invalid (message on stderr).
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const SEMVER_TAG = /^v\d+\.\d+\.\d+$/;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const SHA1 = /^[0-9a-f]{40}$/;
+const ISO8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const REQUIRED_PLATFORMS = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64', 'win32-x64'];
+
+/** Deep scan: any string field equal to "TEMPLATE" is a release blocker. */
+export function findTemplatePlaceholders(value, path = '$') {
+  const hits = [];
+  if (typeof value === 'string') {
+    if (value === 'TEMPLATE') hits.push(path);
+  } else if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++)
+      hits.push(...findTemplatePlaceholders(value[i], `${path}[${i}]`));
+  } else if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value))
+      hits.push(...findTemplatePlaceholders(v, `${path}.${k}`));
+  }
+  return hits;
+}
+
+/**
+ * Validate a parsed manifest object. Returns an array of error strings
+ * (empty when valid). Pure function — safe to unit-test without IO.
+ */
+export function validateManifest(manifest, { strict = false } = {}) {
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return ['manifest must be a JSON object'];
+  }
+
+  // 1. No unmaterialized TEMPLATE placeholders anywhere.
+  const placeholders = findTemplatePlaceholders(manifest);
+  for (const p of placeholders) errors.push(`${p} is an unmaterialized TEMPLATE placeholder`);
+
+  // 2. Top-level identity.
+  if (typeof manifest.id !== 'string' || !manifest.id)
+    errors.push('$.id must be a non-empty string');
+  if (manifest.immutable !== true)
+    errors.push('$.immutable must be true for a publishable manifest');
+  if (typeof manifest.createdAt !== 'string' || !ISO8601.test(manifest.createdAt)) {
+    errors.push('$.createdAt must be an ISO-8601 timestamp');
+  }
+  if (typeof manifest.stableVersion !== 'string' || !SEMVER_TAG.test(manifest.stableVersion)) {
+    errors.push(
+      '$.stableVersion must be an immutable vMAJOR.MINOR.PATCH tag (single source of truth)'
+    );
+  }
+
+  // 3. Component provenance (launcher/opencode/plugin/provider).
+  for (const comp of ['launcher', 'opencode', 'plugin', 'provider']) {
+    const node = manifest[comp];
+    if (!node || typeof node !== 'object') {
+      errors.push(`$.${comp} must be an object`);
+      continue;
+    }
+    if (typeof node.sourceSha !== 'string' || !SHA1.test(node.sourceSha)) {
+      errors.push(`$.${comp}.sourceSha must be a 40-character lowercase hex commit SHA`);
+    }
+    if (typeof node.version !== 'string' || !SEMVER.test(node.version)) {
+      errors.push(`$.${comp}.version must be MAJOR.MINOR.PATCH`);
+    }
+  }
+
+  // 4. Platforms — every required platform present with a real artifact.
+  if (!manifest.platforms || typeof manifest.platforms !== 'object') {
+    errors.push('$.platforms must be an object');
+  } else {
+    for (const plat of REQUIRED_PLATFORMS) {
+      const entry = manifest.platforms[plat];
+      if (!entry || typeof entry !== 'object') {
+        errors.push(`$.platforms.${plat} is missing`);
+        continue;
+      }
+      if (typeof entry.url !== 'string' || !/^https:\/\//.test(entry.url)) {
+        errors.push(`$.platforms.${plat}.url must be an https URL`);
+      }
+      if (typeof entry.sha256 !== 'string' || !SHA256.test(entry.sha256)) {
+        errors.push(`$.platforms.${plat}.sha256 must be a 64-character lowercase hex SHA-256`);
+      }
+      if (
+        typeof entry.sizeBytes !== 'number' ||
+        !Number.isFinite(entry.sizeBytes) ||
+        entry.sizeBytes <= 0
+      ) {
+        errors.push(`$.platforms.${plat}.sizeBytes must be a positive number`);
+      }
+      // signatureUrl may be null for unsigned artifacts, but must not be TEMPLATE.
+      if (
+        entry.signatureUrl !== null &&
+        (typeof entry.signatureUrl !== 'string' || !/^https:\/\//.test(entry.signatureUrl))
+      ) {
+        errors.push(`$.platforms.${plat}.signatureUrl must be an https URL or null`);
+      }
+    }
+    // Reject unknown platforms that snuck in (keeps the manifest honest).
+    for (const plat of Object.keys(manifest.platforms)) {
+      if (!REQUIRED_PLATFORMS.includes(plat)) {
+        errors.push(`$.platforms.${plat} is not a recognized platform`);
+      }
+    }
+  }
+
+  // 5. Supply-chain refs — must be present and materialized (or explicitly null
+  //    with a documented reason, in non-strict mode).
+  for (const ref of ['sbomRef', 'provenanceRef', 'thirdPartyNoticesRef']) {
+    const v = manifest[ref];
+    if (typeof v !== 'string' || !v) errors.push(`$.${ref} must be a non-empty reference`);
+  }
+  if (strict) {
+    if (typeof manifest.signatureRef !== 'string' || !manifest.signatureRef) {
+      errors.push('$.signatureRef must be present in strict mode (signed releases)');
+    }
+  }
+
+  return errors;
+}
+
+function main() {
+  const [file, ...rest] = process.argv.slice(2);
+  if (!file) {
+    console.error('usage: node scripts/validate-manifest.mjs <manifest.json> [--strict]');
+    process.exit(2);
+  }
+  const strict = rest.includes('--strict');
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    console.error(`cannot read/parse manifest ${file}: ${err.message}`);
+    process.exit(1);
+  }
+  const errors = validateManifest(parsed, { strict });
+  if (errors.length) {
+    for (const e of errors) console.error(`✗ ${e}`);
+    console.error(
+      `manifest ${file} is not publishable (${errors.length} blocker${errors.length === 1 ? '' : 's'})`
+    );
+    process.exit(1);
+  }
+  console.log(`✓ manifest ${file} is publishable`);
+  process.exit(0);
+}
+
+// Run as CLI only when invoked directly, not when imported by tests.
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main();
+}

package/scripts/verify-runtime-provider.ts

@@ -0,0 +1,9 @@
+const runtime = await import('@capix/runtime-provider');
+if (typeof runtime.capix !== 'function') {
+  throw new Error('@capix/runtime-provider does not export the capix provider factory');
+}
+const model = runtime.capix('auto');
+if (model.specificationVersion !== 'v2' || model.provider !== 'capix') {
+  throw new Error('@capix/runtime-provider does not implement the pinned LanguageModelV2 contract');
+}
+console.log('@capix/runtime-provider: bundled provider contract verified');

package/scripts/write-release-entry.mjs

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const [version, platform, arch, archive] = process.argv.slice(2);
+if (!version || !platform || !arch || !archive) process.exit(2);
+
+const shaPattern = /^[0-9a-f]{40}$/i;
+const githubSha = process.env.GITHUB_SHA?.trim();
+let sourceSha;
+if (githubSha) {
+  if (!shaPattern.test(githubSha)) throw new Error('GITHUB_SHA must be a 40-character hexadecimal commit SHA');
+  sourceSha = githubSha.toLowerCase();
+} else {
+  if (process.env.CI) throw new Error('GITHUB_SHA is required when generating release metadata in CI');
+  sourceSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    cwd: new URL('..', import.meta.url).pathname,
+    encoding: 'utf8',
+  }).trim();
+  if (!shaPattern.test(sourceSha)) throw new Error('git rev-parse returned an invalid source SHA');
+}
+const entry = {
+  schemaVersion: 1,
+  product: 'capix-code',
+  version,
+  platform: `${platform}-${arch}`,
+  artifact: basename(archive),
+  sha256: createHash('sha256').update(readFileSync(archive)).digest('hex'),
+  sizeBytes: statSync(archive).size,
+  sourceSha,
+  signed: false,
+};
+
+writeFileSync(
+  join(dirname(archive), `capix-code-${version}-${platform}-${arch}.release.json`),
+  `${JSON.stringify(entry, null, 2)}\n`
+);