tines 0.0.235 → 0.0.237

package/README.md

@@ -73,6 +73,12 @@ tines workflows preview review.json --choices choices.json --plan-out review.pla
 tines workflows install review.json --plan review.plan.json --confirm sha256:<plan-digest>
 ```
 
+`preview` and `install` also accept a canonical public snapshot URL. Same-instance URLs keep hosted
+withdrawal checks; foreign URLs are fetched directly by the CLI without forwarding the destination
+API key, cookies, proxy authorization, or referrer. A foreign-source install re-downloads the URL and
+requires the exact reviewed bytes. See the
+[workflow package guide](https://github.com/tbuckley/tines/blob/main/docs/workflow-packages.md).
+
 Workflow names are accepted only when unique; use the ID when duplicate names exist. Export
 selection is explicit: `--project`, repeatable `--schedule`, repeatable
 `--tier '<state-id>=balanced'`, `--project-routing`, and `--inputs declarations.json` add

package/dist/index.js

@@ -4225,6 +4225,48 @@ function createApiClient(options) {
     getWorkflowPackageReceipt: (planId) => get(
       `/api/v1/library/installs/${encodeURIComponent(planId)}`
     ),
+    validatePublication: (body) => request(
+      "POST",
+      "/api/v1/publications/validate",
+      body
+    ),
+    preparePublication: (body) => request(
+      "POST",
+      "/api/v1/publications/prepare",
+      body
+    ),
+    publishPublication: (candidateId, body) => request(
+      "POST",
+      `/api/v1/publications/${encodeURIComponent(candidateId)}/publish`,
+      body
+    ),
+    getPublicationResult: (candidateId) => get(
+      `/api/v1/publications/${encodeURIComponent(candidateId)}/result`
+    ),
+    listPublications: (workflow2) => get(
+      `/api/v1/publications${query({ workflow: workflow2 })}`
+    ),
+    withdrawPublication: (snapshotId) => request(
+      "POST",
+      `/api/v1/publications/${encodeURIComponent(snapshotId)}/withdraw`
+    ),
+    restorePublication: (snapshotId) => request(
+      "POST",
+      `/api/v1/publications/${encodeURIComponent(snapshotId)}/restore`
+    ),
+    getPublicSnapshot: (snapshotId) => get(
+      `/api/v1/publications/public/${encodeURIComponent(snapshotId)}`
+    ),
+    getPublicSnapshotStatus: (snapshotId) => get(
+      `/api/v1/publications/public/${encodeURIComponent(snapshotId)}/status`
+    ),
+    prepareHostedWorkflowPackage: (snapshotId, choices = {}) => request(
+      "POST",
+      `/api/v1/publications/public/${encodeURIComponent(snapshotId)}/prepare-install`,
+      { choices }
+    ),
+    downloadPublicSnapshot: (snapshotId) => raw("GET", `/api/v1/publications/public/${encodeURIComponent(snapshotId)}/download`),
+    downloadPublicationReuseNotice: (snapshotId) => raw("GET", `/api/v1/publications/public/${encodeURIComponent(snapshotId)}/reuse.txt`),
     validateLibrary: (body) => request(
       "POST",
       "/api/v1/library/validate",
@@ -5494,6 +5536,27 @@ function parseStrictLibraryJson(source) {
 // ../shared/src/library/choices.ts
 var PACKAGE_CHOICES_MAX_BYTES = 512 * 1024;
 
+// ../shared/src/publications.ts
+var PUBLIC_WORKFLOW_MAX_BYTES = 1048576;
+var PUBLICATION_CANDIDATE_TTL_MS = 15 * 60 * 1e3;
+var SNAPSHOT_ID = /^[A-Za-z0-9_-]{20,100}$/;
+function parsePublicSnapshotReference(value, configuredOrigin) {
+  if (SNAPSHOT_ID.test(value)) return value;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Expected a publication ID or canonical public URL");
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash)
+    throw new Error("Invalid public publication URL");
+  if (configuredOrigin && url.origin !== new URL(configuredOrigin).origin)
+    throw new Error("external_source_requires_download");
+  const match = /^\/p\/([A-Za-z0-9_-]{20,100})(?:\/download)?$/.exec(url.pathname);
+  if (!match || url.search) throw new Error("Invalid public publication URL");
+  return match[1];
+}
+
 // ../shared/src/usage.ts
 function usageCostLabel(cost, finalized = 1) {
   if (finalized === 0) return "No runs";
@@ -12497,6 +12560,7 @@ function register10(program3) {
 
 // src/commands/workflows.ts
 import { readFileSync as readFileSync12 } from "node:fs";
+import { createInterface as createInterface5 } from "node:readline/promises";
 
 // src/workflow-packages.ts
 import { createInterface as createInterface4 } from "node:readline/promises";
@@ -12526,12 +12590,13 @@ function readStrictObject(path2, label) {
 function normalizeApiBase(value) {
   return new URL(value).toString().replace(/\/$/, "");
 }
-function saveWorkflowPackagePlan(path2, apiBase, plan) {
+function saveWorkflowPackagePlan(path2, apiBase, plan, remoteSource) {
   const saved = {
     format: "tines.workflow-install-plan",
     version: 1,
     api_base: normalizeApiBase(apiBase),
     document_digest: plan.document_digest,
+    ...remoteSource ? { remote_source: remoteSource } : {},
     plan
   };
   writeJsonFile(path2, saved, { secret: true });
@@ -12539,7 +12604,7 @@ function saveWorkflowPackagePlan(path2, apiBase, plan) {
 }
 function readWorkflowPackagePlan(path2) {
   const saved = readStrictObject(path2, "plan file");
-  const outerKeys = ["format", "version", "api_base", "document_digest", "plan"];
+  const outerKeys = ["format", "version", "api_base", "document_digest", "remote_source", "plan"];
   const planKeys = [
     "operations",
     "document",
@@ -12553,9 +12618,17 @@ function readWorkflowPackagePlan(path2) {
     "actor_key",
     "compiler_version",
     "plan_token",
-    "budget"
+    "budget",
+    "source"
   ];
-  if (Object.keys(saved).length !== outerKeys.length || !Object.keys(saved).every((key) => outerKeys.includes(key)) || saved.format !== "tines.workflow-install-plan" || saved.version !== 1 || typeof saved.api_base !== "string" || typeof saved.document_digest !== "string" || !saved.plan || typeof saved.plan !== "object" || typeof saved.plan.plan_token !== "string" || typeof saved.plan.plan_digest !== "string" || Object.keys(saved.plan).length !== planKeys.length || !Object.keys(saved.plan).every((key) => planKeys.includes(key))) {
+  if (![5, 6].includes(Object.keys(saved).length) || !Object.keys(saved).every((key) => outerKeys.includes(key)) || saved.format !== "tines.workflow-install-plan" || saved.version !== 1 || typeof saved.api_base !== "string" || typeof saved.document_digest !== "string" || !saved.plan || typeof saved.plan !== "object" || typeof saved.plan.plan_token !== "string" || typeof saved.plan.plan_digest !== "string" || ![planKeys.length - 1, planKeys.length].includes(
+    Object.keys(saved.plan).length
+  ) || !Object.keys(saved.plan).every((key) => planKeys.includes(key))) {
+    throw new Error("invalid workflow package plan file");
+  }
+  if (saved.remote_source !== void 0 && (!saved.remote_source || typeof saved.remote_source !== "object" || Object.keys(saved.remote_source).length !== 2 || typeof saved.remote_source.url !== "string" || !/^sha256:[0-9a-f]{64}$/.test(
+    String(saved.remote_source.bytes_sha256)
+  ))) {
     throw new Error("invalid workflow package plan file");
   }
   const result = saved;
@@ -12677,7 +12750,8 @@ function assertPlanBinding(plan) {
     actor_key: plan.actor_key,
     compiler_version: plan.compiler_version,
     allocation: plan.allocation,
-    budget: plan.budget
+    budget: plan.budget,
+    ...plan.source ? { source: plan.source } : {}
   };
   for (const [field, value] of Object.entries(mirrors)) {
     const signedField = field === "id" ? "id" : field;
@@ -12794,10 +12868,16 @@ function formatValidation(result) {
 }
 async function localDocument(path2) {
   const raw = readPackageSource(path2);
+  return packageDocument(raw);
+}
+async function packageDocument(raw) {
   const document = await parseLibraryV3Document(raw);
   if (document.profile !== "workflow") throw new Error("expected a workflow-profile package");
   return { raw, document };
 }
+function workflowPackageBytesSha256(raw) {
+  return `sha256:${createHash2("sha256").update(raw).digest("hex")}`;
+}
 function canonicalWorkflowPackage(document) {
   return canonicalizeLibraryValue(document);
 }
@@ -12841,7 +12921,218 @@ async function recoverOrInstall(api, raw, plan) {
   }
 }
 
+// src/publication-fetch.ts
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+var SNAPSHOT_PATH = /^\/p\/[A-Za-z0-9_-]{20,100}(?:\/download)?$/;
+var MAX_REDIRECTS = 3;
+var DEFAULT_TIMEOUT_MS = 3e4;
+function mappedIpv4(address) {
+  const match = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address);
+  if (match) return match[1];
+  const hexadecimal = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(address);
+  if (!hexadecimal) return void 0;
+  const high = Number.parseInt(hexadecimal[1], 16);
+  const low = Number.parseInt(hexadecimal[2], 16);
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
+function isLoopback(address) {
+  const mapped = mappedIpv4(address);
+  if (mapped) return isLoopback(mapped);
+  return address === "::1" || /^127\./.test(address);
+}
+function ipv6Integer(address) {
+  let value = address.toLowerCase();
+  const dotted = /(?:^|:)(\d{1,3}(?:\.\d{1,3}){3})$/.exec(value);
+  if (dotted) {
+    const octets = dotted[1].split(".").map(Number);
+    if (octets.some((octet) => octet > 255)) return void 0;
+    value = `${value.slice(0, dotted.index)}:${(octets[0] << 8 | octets[1]).toString(16)}:${(octets[2] << 8 | octets[3]).toString(16)}`;
+  }
+  const halves = value.split("::");
+  if (halves.length > 2) return void 0;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves[1] ? halves[1].split(":") : [];
+  const missing = 8 - left.length - right.length;
+  if (halves.length === 1 && missing !== 0 || missing < 0) return void 0;
+  const groups = [...left, ...Array(missing).fill("0"), ...right];
+  if (groups.length !== 8 || groups.some((group) => !/^[0-9a-f]{1,4}$/.test(group)))
+    return void 0;
+  return groups.reduce((result, group) => result << 16n | BigInt(`0x${group}`), 0n);
+}
+function inIpv6Range(value, base, prefix) {
+  const baseValue = ipv6Integer(base);
+  if (baseValue === void 0) return false;
+  const shift = BigInt(128 - prefix);
+  return value >> shift === baseValue >> shift;
+}
+function isPublicAddress(address) {
+  const mapped = mappedIpv4(address);
+  if (mapped) return isPublicAddress(mapped);
+  if (isIP(address) === 4) {
+    const [a, b] = address.split(".").map(Number);
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 0 || a === 192 && b === 2 || a === 192 && b === 88 || a === 192 && b === 168 || a === 198 && (b === 18 || b === 19) || a === 198 && b === 51 || a === 203 && b === 0 && Number(address.split(".")[2]) === 113);
+  }
+  if (isIP(address) === 6) {
+    const value = ipv6Integer(address);
+    if (value === void 0 || !inIpv6Range(value, "2000::", 3)) return false;
+    return ![
+      ["2001::", 23],
+      // IETF protocol assignments, including Teredo and benchmarking
+      ["2001:db8::", 32],
+      // documentation
+      ["2002::", 16],
+      // 6to4 (may embed a private IPv4 destination)
+      ["2620:4f:8000::", 48],
+      // documentation
+      ["3fff::", 20]
+      // documentation
+    ].some(([base, prefix]) => inIpv6Range(value, base, prefix));
+  }
+  return false;
+}
+function validateHop(url, initial) {
+  if (!["http:", "https:"].includes(url.protocol))
+    throw new Error("publication URL must use HTTPS");
+  if (url.username || url.password) throw new Error("publication URL must not contain credentials");
+  if (url.hash) throw new Error("publication URL must not contain a fragment");
+  if (url.search) throw new Error("publication URL must not contain query parameters");
+  if (initial && !SNAPSHOT_PATH.test(url.pathname))
+    throw new Error("expected a canonical public snapshot or download URL");
+}
+async function pinnedAddress(url, lookup) {
+  const hostname4 = url.hostname.replace(/^\[|\]$/g, "");
+  const literalFamily = isIP(hostname4);
+  const addresses = literalFamily ? [{ address: hostname4, family: literalFamily }] : await lookup(hostname4, { all: true, verbatim: true });
+  if (!addresses.length) throw new Error(`publication host ${url.hostname} did not resolve`);
+  const loopbackDevelopment = url.protocol === "http:" && (url.hostname === "localhost" || addresses.every(({ address }) => isLoopback(address)));
+  if (url.protocol === "http:" && !loopbackDevelopment)
+    throw new Error(
+      "publication URL must use HTTPS (HTTP is allowed only for loopback development)"
+    );
+  if (!loopbackDevelopment && addresses.some(({ address }) => !isPublicAddress(address)))
+    throw new Error("publication URL resolves to a private or reserved address");
+  return addresses[0];
+}
+async function readHop(url, options) {
+  const pinned = await pinnedAddress(url, options.lookup);
+  return new Promise((resolve2, reject) => {
+    const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(
+      url,
+      {
+        method: "GET",
+        headers: { accept: "application/json" },
+        lookup: (_hostname, _opts, callback) => callback(null, pinned.address, pinned.family)
+      },
+      (response) => {
+        const status = response.statusCode ?? 0;
+        if (status >= 300 && status < 400) {
+          response.resume();
+          const location = response.headers.location;
+          if (!location) return reject(new Error("publication redirect has no destination"));
+          try {
+            return resolve2({ redirect: new URL(location, url) });
+          } catch {
+            return reject(new Error("publication redirect has an invalid destination"));
+          }
+        }
+        if (status !== 200) {
+          response.resume();
+          return reject(new Error(`publication download returned HTTP ${status}`));
+        }
+        const contentType = String(response.headers["content-type"] ?? "").split(";", 1)[0].trim().toLowerCase();
+        if (contentType !== "application/json") {
+          response.resume();
+          return reject(new Error("publication download must be application/json"));
+        }
+        const encoding = String(response.headers["content-encoding"] ?? "identity").toLowerCase();
+        if (encoding !== "identity") {
+          response.resume();
+          return reject(new Error("publication download uses unsupported content encoding"));
+        }
+        let size = 0;
+        const chunks = [];
+        response.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > options.maxBytes)
+            response.destroy(new Error("publication download is too large"));
+          else chunks.push(chunk);
+        });
+        response.on("end", () => {
+          try {
+            resolve2({
+              body: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+                Buffer.concat(chunks)
+              )
+            });
+          } catch {
+            reject(new Error("publication download is not valid UTF-8"));
+          }
+        });
+      }
+    );
+    const deadline = setTimeout(
+      () => request.destroy(new Error("publication download timed out")),
+      options.timeoutMs
+    );
+    request.on("close", () => clearTimeout(deadline));
+    request.on("error", reject);
+    request.end();
+  });
+}
+async function fetchPublicWorkflowPackage(value, options = {}) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("expected a canonical public snapshot or download URL");
+  }
+  validateHop(url, true);
+  if (!url.pathname.endsWith("/download")) url.pathname += "/download";
+  const sourceUrl = url.toString();
+  for (let redirects = 0; ; redirects += 1) {
+    validateHop(url, false);
+    const result = await readHop(url, {
+      lookup: options.lookup ?? dnsLookup,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      maxBytes: options.maxBytes ?? PUBLIC_WORKFLOW_MAX_BYTES
+    });
+    if (result.body !== void 0) return { raw: result.body, sourceUrl };
+    if (!result.redirect || redirects >= MAX_REDIRECTS)
+      throw new Error("publication download exceeded three redirects");
+    if (url.protocol === "https:" && result.redirect.protocol !== "https:")
+      throw new Error("publication redirect must not downgrade HTTPS");
+    url = result.redirect;
+  }
+}
+
 // src/commands/workflows.ts
+function savePublicationProof(path2, apiBase, proof) {
+  const saved = {
+    format: "tines.workflow-publication-proof",
+    version: 1,
+    api_base: normalizeUrl(apiBase),
+    proof
+  };
+  writeJsonFile(path2, saved, { secret: true });
+  return saved;
+}
+function readPublicationProof(path2) {
+  const saved = readStrictObject(path2, "publication proof");
+  if (saved.format !== "tines.workflow-publication-proof" || saved.version !== 1 || typeof saved.api_base !== "string" || !saved.proof || typeof saved.proof.candidate_id !== "string" || typeof saved.proof.review_digest !== "string")
+    die("invalid workflow publication proof file");
+  return saved;
+}
+async function confirmPublicationAction(question) {
+  const rl = createInterface5({ input: process.stdin, output: process.stderr });
+  try {
+    return /^(?:y|yes)$/i.test((await rl.question(`${question} [y/N] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
 function readJsonBody(inline, file) {
   if (inline !== void 0 && file !== void 0) {
     die("pass the JSON inline or with --file, not both");
@@ -13152,7 +13443,150 @@ async function resolveExportState(api, ref) {
   if (named.length > 1) die(`state name "${ref}" is ambiguous; use an id`);
   die(`no state named "${ref}"; use a state id or <workflow>/<state>`);
 }
+function publicationSource(value, apiBase) {
+  if (!/^https?:\/\//i.test(value)) return { kind: "file" };
+  try {
+    return {
+      kind: "hosted",
+      snapshotId: parsePublicSnapshotReference(value, apiBase)
+    };
+  } catch (error) {
+    if (error instanceof Error && error.message === "external_source_requires_download")
+      return { kind: "remote" };
+    throw error;
+  }
+}
 function registerPackageCommands(workflows) {
+  withCommon(
+    workflows.command("publication-validate <file>").description("Validate a workflow package for text-only public hosting")
+  ).action(async (path2, opts) => {
+    const result = await client(opts).validatePublication({
+      document_json: readPackageSource(path2)
+    });
+    if (opts.json) printJson(result);
+    else {
+      console.log(
+        result.valid ? "valid public workflow snapshot" : "invalid public workflow snapshot"
+      );
+      for (const diagnostic of result.diagnostics)
+        console.log(`  ${diagnostic.path || "/"}: ${diagnostic.message}`);
+    }
+    if (!result.valid) process.exitCode = 1;
+  });
+  withCommon(
+    workflows.command("publish [workflow]").description("Prepare or commit one exact immutable public workflow snapshot").option(
+      "--from <file>",
+      "prepare from an existing workflow package instead of an owned workflow"
+    ).option("--proof-out <file>", "save the complete prepared proof with mode 0600").option("--proof <file>", "commit a previously saved exact proof").option("--display-name <name>", "public attribution name (never an email)").option("--license <license>", "reuse license (currently MIT)", "MIT").option("--license-year <year>", "MIT copyright year", String((/* @__PURE__ */ new Date()).getFullYear())).option("--confirm <review-digest>", "exact digest of the reviewed proof").option("--sharing-rights", "confirm rights to every bundled declaration and file").option("--recover", "reconcile this same candidate after a lost response").option("--repo <local-id>", "confirm one bundled repository ID (repeatable)", collect2, [])
+  ).action(
+    async (workflow2, opts) => {
+      const apiBase = normalizeUrl(resolveUrl(opts));
+      const api = client(opts);
+      if (opts.proof) {
+        if (workflow2 || opts.from || opts.proofOut || opts.displayName)
+          die(
+            "--proof commit mode cannot be combined with a workflow, --from, --proof-out, or --display-name"
+          );
+        const saved = readPublicationProof(opts.proof);
+        if (normalizeUrl(saved.api_base) !== apiBase)
+          die(`proof belongs to ${saved.api_base}, not ${apiBase}`);
+        const proof2 = saved.proof;
+        if (opts.confirm && opts.confirm !== proof2.review_digest)
+          die(`confirmation digest does not match reviewed proof ${proof2.review_digest}`);
+        if (!process.stdin.isTTY && (opts.confirm !== proof2.review_digest || !opts.sharingRights))
+          die(`non-interactive publish requires --confirm ${proof2.review_digest} --sharing-rights`);
+        if (process.stdin.isTTY && !opts.confirm) {
+          process.stderr.write(`${JSON.stringify(proof2, null, 2)}
+`);
+          if (!await confirmPublicationAction("Publish these exact immutable bytes?"))
+            die("publication declined");
+          if (!await confirmPublicationAction("Do you have sharing rights for every bundled item?"))
+            die("publication declined");
+        }
+        let result;
+        if (opts.recover) {
+          try {
+            result = await api.getPublicationResult(proof2.candidate_id);
+          } catch (error) {
+            if (!(error instanceof ApiError) || error.status !== 404) throw error;
+          }
+        }
+        result ??= await api.publishPublication(proof2.candidate_id, {
+          review_digest: proof2.review_digest,
+          sharing_rights: true,
+          exact_content: true,
+          reviewed_repo_ids: opts.repo
+        });
+        if (opts.json) printJson(result);
+        else console.log(`published ${result.receipt.public_url}`);
+        return;
+      }
+      if (opts.recover) die("--recover requires --proof");
+      if (!!workflow2 === !!opts.from) die("provide exactly one owned workflow or --from <file>");
+      if (!opts.proofOut) die("preparing a publication requires --proof-out <file>");
+      if (!opts.displayName) die("preparing a publication requires --display-name <name>");
+      if (opts.license !== "MIT") die("--license currently supports only MIT");
+      const year = Number(opts.licenseYear);
+      if (!Number.isSafeInteger(year)) die("--license-year must be an integer");
+      const source = opts.from ? { kind: "file", document_json: readPackageSource(opts.from) } : {
+        kind: "owned_workflow",
+        workflow_id: (await resolveWorkflow(api, workflow2)).id,
+        options: { schedule_ids: [], tiers: [] }
+      };
+      const proof = await api.preparePublication({
+        prepare_request_id: crypto.randomUUID(),
+        source,
+        metadata: { display_name: opts.displayName, license: "MIT", license_year: year }
+      });
+      savePublicationProof(opts.proofOut, apiBase, proof);
+      if (opts.json) printJson(proof);
+      else {
+        console.log(JSON.stringify(proof, null, 2));
+        console.error(`saved exact publication proof to ${opts.proofOut}`);
+      }
+    }
+  );
+  withCommon(
+    workflows.command("publications").description("List your public workflow snapshots").option("--workflow <id>", "filter by owned source workflow ID")
+  ).action(async (opts) => {
+    const result = await client(opts).listPublications(opts.workflow);
+    if (opts.json) printJson(result);
+    else if (!result.items.length) console.log("no public snapshots");
+    else
+      table([
+        ["NAME", "STATUS", "PUBLISHED", "SNAPSHOT"],
+        ...result.items.map((item) => [
+          item.metadata.display_name,
+          item.owner_state === "published" && item.host_state === "active" ? "hosted" : "unavailable",
+          new Date(item.published_at).toISOString(),
+          item.snapshot_id
+        ])
+      ]);
+  });
+  withCommon(
+    workflows.command("unpublish <public-url-or-id>").description("Withdraw a hosted public snapshot").option("-y, --yes", "skip the explicit withdrawal prompt")
+  ).action(async (reference, opts) => {
+    if (!opts.yes && !process.stdin.isTTY) die("non-interactive withdrawal requires --yes");
+    if (!opts.yes && !await confirmPublicationAction("Withdraw this hosted snapshot now?"))
+      die("withdrawal declined");
+    const apiBase = normalizeUrl(resolveUrl(opts));
+    const snapshotId = /^https?:/i.test(reference) ? parsePublicSnapshotReference(reference, apiBase) : reference;
+    const result = await client(opts).withdrawPublication(snapshotId);
+    if (opts.json) printJson(result);
+    else console.log(`withdrew ${result.receipt.public_url}`);
+  });
+  withCommon(
+    workflows.command("restore-publication <public-url-or-id>").description("Restore an owner-withdrawn public snapshot when host policy permits").option("-y, --yes", "skip the explicit restoration prompt")
+  ).action(async (reference, opts) => {
+    if (!opts.yes && !process.stdin.isTTY) die("non-interactive restoration requires --yes");
+    if (!opts.yes && !await confirmPublicationAction("Restore this hosted snapshot now?"))
+      die("restoration declined");
+    const apiBase = normalizeUrl(resolveUrl(opts));
+    const snapshotId = /^https?:/i.test(reference) ? parsePublicSnapshotReference(reference, apiBase) : reference;
+    const result = await client(opts).restorePublication(snapshotId);
+    if (opts.json) printJson(result);
+    else console.log(`restored ${result.receipt.public_url}`);
+  });
   withCommon(
     workflows.command("export <workflow-id-or-unambiguous-name>").description("Export a canonical workflow package JSON document").option("--project <id-or-name>", "source project for selected project-bound configuration").option("--schedule <id>", "include this source schedule ID (repeatable)", collect2, []).option(
       "--tier <state-ref=tier>",
@@ -13193,25 +13627,57 @@ function registerPackageCommands(workflows) {
     }
   );
   withCommon(
-    workflows.command("validate <file>").description("Validate a workflow package file (use - for stdin)")
+    workflows.command("validate <file>").description("Validate a workflow package file (use - for stdin)").option("--public", "apply the stricter text-only public-hosting policy")
   ).action(async (path2, opts) => {
-    const result = await client(opts).validateLibrary({ document_json: readPackageSource(path2) });
+    const api = client(opts);
+    if (opts.public) {
+      const result2 = await api.validatePublication({ document_json: readPackageSource(path2) });
+      if (opts.json) printJson(result2);
+      else {
+        console.log(
+          result2.valid ? "valid public workflow snapshot" : "invalid public workflow snapshot"
+        );
+        for (const diagnostic of result2.diagnostics)
+          console.log(`  ${diagnostic.path || "/"}: ${diagnostic.message}`);
+      }
+      if (!result2.valid) process.exitCode = 1;
+      return;
+    }
+    const result = await api.validateLibrary({ document_json: readPackageSource(path2) });
     if (opts.json) printJson(result);
     else console.log(formatValidation(result));
     if (!result.valid) process.exitCode = 1;
   });
   withCommon(
-    workflows.command("preview <file>").description("Prepare and fully review a destination workflow package plan").option("--choices <file>", "destination choices JSON file").option("--plan-out <file>", "atomically save the signed plan for a later install")
+    workflows.command("preview <file-or-public-url>").description("Prepare and fully review a destination workflow package plan").option("--choices <file>", "destination choices JSON file").option("--plan-out <file>", "atomically save the signed plan for a later install")
   ).action(async (path2, opts) => {
-    const raw = readPackageSource(path2);
     const choices = opts.choices ? readStrictObject(opts.choices, "choices file") : void 0;
-    const plan = await client(opts).prepareWorkflowPackage({ document_json: raw, choices });
-    if (opts.planOut) saveWorkflowPackagePlan(opts.planOut, resolveUrl(opts), plan);
+    const apiBase = normalizeUrl(resolveUrl(opts));
+    const api = client(opts);
+    const source = publicationSource(path2, apiBase);
+    let remoteSource;
+    let plan;
+    if (source.kind === "hosted") {
+      plan = await api.prepareHostedWorkflowPackage(source.snapshotId, choices);
+    } else {
+      if (source.kind === "remote") {
+        const fetched = await fetchPublicWorkflowPackage(path2);
+        remoteSource = {
+          url: fetched.sourceUrl,
+          bytes_sha256: workflowPackageBytesSha256(fetched.raw)
+        };
+        plan = await api.prepareWorkflowPackage({ document_json: fetched.raw, choices });
+      } else {
+        const raw = readPackageSource(path2);
+        plan = await api.prepareWorkflowPackage({ document_json: raw, choices });
+      }
+    }
+    if (opts.planOut) saveWorkflowPackagePlan(opts.planOut, apiBase, plan, remoteSource);
     if (opts.json) printJson(plan);
     else console.log(formatWorkflowPackageReview(plan));
   });
   withCommon(
-    workflows.command("install <file>").description("Install one exactly reviewed workflow package plan").option("--choices <file>", "destination choices JSON file (interactive preparation only)").option("--plan <file>", "signed plan saved by workflows preview").option("--confirm <plan-digest>", "exact reviewed plan digest (required outside a TTY)")
+    workflows.command("install <file-or-public-url>").description("Install one exactly reviewed workflow package plan").option("--choices <file>", "destination choices JSON file (interactive preparation only)").option("--plan <file>", "signed plan saved by workflows preview").option("--confirm <plan-digest>", "exact reviewed plan digest (required outside a TTY)")
   ).action(
     async (path2, opts) => {
       if (path2 === "-" && process.stdin.isTTY)
@@ -13226,15 +13692,33 @@ function registerPackageCommands(workflows) {
         die(
           "stdin package input cannot also provide interactive confirmation; use preview --plan-out first"
         );
-      const { raw, document } = await localDocument(path2);
       const apiBase = normalizeUrl(resolveUrl(opts));
       const api = client(opts);
+      const source = publicationSource(path2, apiBase);
+      let raw;
       let plan;
       let planPath = opts.plan;
       if (planPath) {
         const saved = readWorkflowPackagePlan(planPath);
         if (normalizeUrl(saved.api_base) !== apiBase)
           die(`plan belongs to ${saved.api_base}, not ${apiBase}`);
+        if (saved.remote_source) {
+          if (source.kind !== "remote")
+            die("saved remote plan must be installed from its public source URL");
+          const fetched = await fetchPublicWorkflowPackage(path2);
+          if (fetched.sourceUrl !== saved.remote_source.url || workflowPackageBytesSha256(fetched.raw) !== saved.remote_source.bytes_sha256)
+            die("public source changed since preview; create and review a fresh plan");
+          raw = fetched.raw;
+        } else if (saved.plan.source?.kind === "hosted_publication") {
+          if (source.kind !== "hosted" || source.snapshotId !== saved.plan.source.snapshot_id)
+            die("saved hosted plan belongs to a different public snapshot");
+          await api.getPublicSnapshotStatus(source.snapshotId);
+          raw = canonicalWorkflowPackage(saved.plan.document);
+        } else {
+          if (source.kind !== "file") die("saved file plan must be installed from its file");
+          raw = readPackageSource(path2);
+        }
+        const { document } = await packageDocument(raw);
         if (saved.document_digest !== document.digest || saved.plan.document_digest !== document.digest || canonicalWorkflowPackage(saved.plan.document) !== canonicalWorkflowPackage(document))
           die(
             `package digest ${document.digest} does not match saved plan ${saved.document_digest}`
@@ -13242,9 +13726,25 @@ function registerPackageCommands(workflows) {
         plan = saved.plan;
       } else {
         const choices = opts.choices ? readStrictObject(opts.choices, "choices file") : void 0;
-        plan = await api.prepareWorkflowPackage({ document_json: raw, choices });
-        planPath = `${path2}.plan.json`;
-        saveWorkflowPackagePlan(planPath, apiBase, plan);
+        let remoteSource;
+        if (source.kind === "hosted") {
+          plan = await api.prepareHostedWorkflowPackage(source.snapshotId, choices);
+          raw = canonicalWorkflowPackage(plan.document);
+        } else if (source.kind === "remote") {
+          const fetched = await fetchPublicWorkflowPackage(path2);
+          raw = fetched.raw;
+          await packageDocument(raw);
+          remoteSource = {
+            url: fetched.sourceUrl,
+            bytes_sha256: workflowPackageBytesSha256(raw)
+          };
+          plan = await api.prepareWorkflowPackage({ document_json: raw, choices });
+        } else {
+          ({ raw } = await localDocument(path2));
+          plan = await api.prepareWorkflowPackage({ document_json: raw, choices });
+        }
+        planPath = source.kind === "file" ? `${path2}.plan.json` : "workflow-publication.plan.json";
+        saveWorkflowPackagePlan(planPath, apiBase, plan, remoteSource);
         console.error(`saved retryable signed plan to ${planPath}`);
       }
       if (opts.confirm !== void 0 && opts.confirm !== plan.plan_digest)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tines",
-  "version": "0.0.235",
+  "version": "0.0.237",
   "description": "CLI for Tines, an orchestration layer for AI agents",
   "repository": {
     "type": "git",