@fabricorg/cli 0.3.1 → 0.3.3

package/dist/fabric.js

@@ -57,7 +57,7 @@ import { Command as Command20 } from "commander";
 // package.json
 var package_default = {
   name: "@fabricorg/cli",
-  version: "0.3.1",
+  version: "0.3.3",
   description: "CLI for the Fabric AI platform",
   keywords: [
     "fabric",
@@ -1369,6 +1369,7 @@ import { chmod } from "fs/promises";
 // src/lib/instructions/paths.ts
 var DRIVE_LETTER = /^[A-Za-z]:/;
 var RESERVED_DEVICE_NAME = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i;
+var FORBIDDEN_NAME_CHARACTER = /[<>:"|?*]/;
 var RESERVED_ROOTS = [".git", ".fabric"];
 var RESERVED_EXACT_PATHS = [".claude/settings.local.json"];
 function hasControlCharacter(input) {
@@ -1418,10 +1419,10 @@ function checkRelativePath(input) {
         detail: input
       };
     }
-    if (segment.includes(":")) {
+    if (FORBIDDEN_NAME_CHARACTER.test(segment)) {
       return {
         ok: false,
-        reason: "alternate_data_stream",
+        reason: "forbidden_character",
         detail: input
       };
     }
@@ -1472,8 +1473,8 @@ function describeRejection(rejection) {
       return `path segment ending in a dot or space refused: ${rejection.detail}`;
     case "reserved_device_name":
       return `reserved device name refused: ${rejection.detail}`;
-    case "alternate_data_stream":
-      return `colon in path refused: ${rejection.detail}`;
+    case "forbidden_character":
+      return `path contains a character Windows will not put in a filename (< > : " | ? *): ${rejection.detail}`;
     case "reserved_path":
       return `this tool never writes or deletes ${RESERVED_ROOTS.join(", ")} or ${RESERVED_EXACT_PATHS.join(", ")}: ${rejection.detail}`;
     case "not_a_regular_file":
@@ -2578,11 +2579,158 @@ function nextLock(input) {
   };
 }
 
+// src/lib/instructions/push.ts
+import { createHash as createHash5 } from "crypto";
+var MAX_PUSH_CHANGES = 50;
+function assertPushablePath(candidate, source) {
+  const check = checkRelativePath(candidate);
+  if (!check.ok) {
+    throw new Error(
+      `Refusing to push: ${describeRejection(check)}. ${source}`
+    );
+  }
+  if (isReservedPath(candidate)) {
+    throw new Error(
+      `Refusing to push: ${describeRejection({
+        ok: false,
+        reason: "reserved_path",
+        detail: candidate
+      })}. ${source}`
+    );
+  }
+}
+function encodeContent(bytes) {
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  const roundTrip = new TextEncoder().encode(text);
+  if (roundTrip.length === bytes.length && roundTrip.every((byte, index) => byte === bytes[index])) {
+    return { content: text, encoding: "utf8" };
+  }
+  return {
+    content: Buffer.from(bytes).toString("base64"),
+    encoding: "base64"
+  };
+}
+function refuseStaleLedger(detail) {
+  throw new Error(
+    `Refusing to push: the sync lock does not match the published version \u2014 ${detail}. Run \`fabric instructions sync\` and try again. Nothing was read and nothing was sent.`
+  );
+}
+function assertLockMatchesManifest(lock, manifest) {
+  const published = new Map(
+    manifest.map((entry) => [entry.path, entry.sha256])
+  );
+  for (const [path5, entry] of Object.entries(lock.files)) {
+    const expected = published.get(path5);
+    if (expected === void 0) {
+      refuseStaleLedger(
+        `it lists ${path5}, which version ${lock.snapshotVersion} does not contain`
+      );
+    }
+    if (expected !== entry.sha256) {
+      refuseStaleLedger(
+        `its record of ${path5} is not the published file`
+      );
+    }
+  }
+  for (const entry of manifest) {
+    if (!Object.hasOwn(lock.files, entry.path)) {
+      refuseStaleLedger(
+        `version ${lock.snapshotVersion} contains ${entry.path}, which the lock does not list`
+      );
+    }
+  }
+}
+function computePushPlan(input) {
+  return __async(this, null, function* () {
+    var _a2, _b;
+    const { root, lock } = input;
+    const lockedPaths = Object.keys(lock.files);
+    for (const lockedPath of lockedPaths) {
+      assertPushablePath(
+        lockedPath,
+        "The lock names a path this tool will not touch."
+      );
+    }
+    assertLockMatchesManifest(lock, input.manifest);
+    const lockCollision = findCollision(lockedPaths);
+    if (lockCollision !== null) {
+      throw new Error(
+        `Refusing to push: ${describeRejection({
+          ok: false,
+          reason: "collision",
+          detail: `${lockCollision.first} and ${lockCollision.second}`
+        })}. The lock names two paths this tool cannot tell apart.`
+      );
+    }
+    const added = [];
+    const locked = new Set(lockedPaths);
+    for (const candidate of (_a2 = input.added) != null ? _a2 : []) {
+      assertPushablePath(candidate, "That path cannot be pushed.");
+      if (locked.has(candidate)) {
+        continue;
+      }
+      if (added.includes(candidate)) {
+        continue;
+      }
+      added.push(candidate);
+    }
+    const allCollision = findCollision([...lockedPaths, ...added]);
+    if (allCollision !== null) {
+      throw new Error(
+        `Refusing to push: ${describeRejection({
+          ok: false,
+          reason: "collision",
+          detail: `${allCollision.first} and ${allCollision.second}`
+        })}. Two of these paths are one file on a case-insensitive filesystem.`
+      );
+    }
+    const entries = [];
+    const changes = [];
+    const unchanged = [];
+    for (const lockedPath of lockedPaths.sort()) {
+      const read = yield readFileSafely(root, lockedPath);
+      if (read === null) {
+        entries.push({ path: lockedPath, action: "delete" });
+        changes.push({ op: "delete", path: lockedPath });
+        continue;
+      }
+      const actual = createHash5("sha256").update(read.bytes).digest("hex");
+      if (actual === ((_b = lock.files[lockedPath]) == null ? void 0 : _b.sha256)) {
+        unchanged.push(lockedPath);
+        continue;
+      }
+      const encoded = encodeContent(read.bytes);
+      entries.push({
+        path: lockedPath,
+        action: "put",
+        size: read.bytes.length
+      });
+      changes.push(__spreadValues({ op: "put", path: lockedPath }, encoded));
+    }
+    for (const newPath of added.sort()) {
+      const read = yield readFileSafely(root, newPath);
+      if (read === null) {
+        throw new Error(
+          `Refusing to push: there is no file at ${newPath}.`
+        );
+      }
+      const encoded = encodeContent(read.bytes);
+      entries.push({ path: newPath, action: "put", size: read.bytes.length });
+      changes.push(__spreadValues({ op: "put", path: newPath }, encoded));
+    }
+    return { entries, changes, unchanged };
+  });
+}
+
 // src/commands/instructions/index.ts
 var HOOK_DEADLINE_MS = 1e4;
 var CHECK_TIMEOUT_MS = 5e3;
 var SYNC_TIMEOUT_MS = 15e3;
 var BUNDLE_TIMEOUT_MS = 6e4;
+var PUSH_TIMEOUT_MS = 6e4;
+function collectAdded(value, previous) {
+  return [...previous, value];
+}
 var CliFailure = class extends Error {
   constructor(message, exitCode) {
     super(message);
@@ -2617,6 +2765,22 @@ function buildInstructionsCommand() {
       yield run(opts, "sync", () => runSync(opts, formatFor(this)));
     });
   });
+  instructions.command("push").description(
+    "Suggest this checkout's edits to the project's coding instructions"
+  ).requiredOption("--project <id>", "Project ID").option("--dest <dir>", "Destination directory (default: cwd)").option("--org <slug>", "Organization context").option(
+    "--add <path>",
+    "Also send a file the last sync did not write (repeatable)",
+    collectAdded,
+    []
+  ).option("--dry-run", "Print the change set and send nothing").option("--format <format>", "Output format: text|json").action(function(opts) {
+    return __async(this, null, function* () {
+      yield run(
+        __spreadProps(__spreadValues({}, opts), { hook: false }),
+        "push",
+        () => runPush(opts, formatFor(this))
+      );
+    });
+  });
   instructions.command("init").description(
     "Write a SessionStart hook for a coding tool and take the first copy"
   ).requiredOption("--project <id>", "Project ID").requiredOption(
@@ -2721,7 +2885,7 @@ function destinationOf(opts) {
   var _a2;
   return path4.resolve((_a2 = opts.dest) != null ? _a2 : process.cwd());
 }
-function instructionsClient(opts, timeoutMs) {
+function instructionsClient(opts, timeoutMs, { neverRetry = false } = {}) {
   if (!getApiKey()) {
     throw new CliFailure(
       "Not authenticated. Run: fabric auth login --key <api-key>",
@@ -2730,11 +2894,22 @@ function instructionsClient(opts, timeoutMs) {
   }
   return getClient(
     opts.hook ? {
+      // Hook mode has ONE absolute deadline covering every
+      // call it makes, so it cannot spend it on retries: a
+      // session that will not start is worse than instructions
+      // one version stale.
       timeoutMs: Math.min(timeoutMs, HOOK_DEADLINE_MS),
       retry: { maxRetries: 0 }
-    } : { timeoutMs }
+    } : neverRetry ? { timeoutMs, retry: { maxRetries: 0 } } : { timeoutMs }
   ).withoutContext();
 }
+function downloadUrlClient(opts) {
+  return instructionsClient(
+    opts,
+    opts.hook ? HOOK_DEADLINE_MS : BUNDLE_TIMEOUT_MS,
+    { neverRetry: true }
+  );
+}
 function orgSlugFor(opts) {
   return opts.org;
 }
@@ -2945,10 +3120,9 @@ function syncOnce(opts) {
       const org = orgSlugFor(opts);
       let download;
       try {
-        download = yield client.instructions.createDownloadUrl(
-          opts.project,
-          { org }
-        );
+        download = yield downloadUrlClient(
+          opts
+        ).instructions.createDownloadUrl(opts.project, { org });
       } catch (error) {
         throw asCliFailure(error);
       }
@@ -3044,6 +3218,153 @@ function reportSync(outcome, opts) {
     line(`Everything in ${outcome.destination} already matched.`);
   }
 }
+function runPush(opts, format) {
+  return __async(this, null, function* () {
+    var _a2;
+    const destination = destinationOf(opts);
+    const root = yield resolveExistingRoot(destination);
+    const lock = yield readLockForProject(root, opts.project);
+    if (lock === null) {
+      throw new CliFailure(
+        `No coding-instructions lock in ${destination}. Run \`fabric instructions sync --project ${opts.project}\` first: a push is a diff against the version that was last applied here, and without that ledger there is nothing to diff against.`,
+        7
+      );
+    }
+    const client = instructionsClient(
+      __spreadProps(__spreadValues({}, opts), { hook: false }),
+      PUSH_TIMEOUT_MS
+    );
+    const published = yield fetchPublished(client, opts);
+    if (!published.published || !published.snapshot) {
+      throw new CliFailure(
+        "this project has no published coding instructions to change yet; the first version is uploaded from the Coding Instructions tab",
+        4
+      );
+    }
+    if (published.snapshot.id !== lock.snapshotId) {
+      throw new CliFailure(
+        "published instructions moved past your last sync; run `fabric instructions sync` then push again",
+        7
+      );
+    }
+    const plan = yield computePushPlan({
+      root,
+      lock,
+      manifest: (_a2 = published.manifest) != null ? _a2 : [],
+      added: opts.add
+    });
+    if (plan.changes.length === 0) {
+      throw new CliFailure(
+        `Nothing to push: every file the last sync wrote still matches version ${lock.snapshotVersion}. Add a new file with --add <path> if you meant to suggest one.`,
+        7
+      );
+    }
+    if (plan.changes.length > MAX_PUSH_CHANGES) {
+      throw new CliFailure(
+        `Too many changes to push (${plan.changes.length} > ${MAX_PUSH_CHANGES}). A change set this large is a replacement rather than an edit \u2014 upload the folder from the project's Coding Instructions tab, which is also the only path that re-reads the project's exclusion rules.`,
+        7
+      );
+    }
+    const outcome = {
+      projectId: opts.project,
+      destination: root,
+      dryRun: Boolean(opts.dryRun),
+      baseSnapshotId: lock.snapshotId,
+      baseVersion: lock.snapshotVersion,
+      put: plan.entries.filter((entry) => entry.action === "put").map((entry) => entry.path),
+      deleted: plan.entries.filter((entry) => entry.action === "delete").map((entry) => entry.path),
+      unchanged: plan.unchanged.length,
+      snapshotId: null,
+      version: null,
+      proposalStatus: null,
+      status: null
+    };
+    if (!opts.dryRun) {
+      try {
+        const submitted = yield client.instructions.submitChange(
+          opts.project,
+          lock.snapshotId,
+          plan.changes,
+          { org: orgSlugFor(opts) }
+        );
+        outcome.snapshotId = submitted.snapshotId;
+        outcome.version = submitted.version;
+        outcome.proposalStatus = submitted.proposalStatus;
+        outcome.status = submitted.status;
+      } catch (error) {
+        throw asPushFailure(error);
+      }
+    }
+    if (format === "json") {
+      printOutput(outcome, { format: "json" });
+      return;
+    }
+    reportPush(outcome);
+  });
+}
+function asPushFailure(error) {
+  const code = error.code;
+  const message = error instanceof Error ? error.message : String(error);
+  switch (code) {
+    case "PULL_FIRST":
+      return new CliFailure(
+        "published instructions moved past your last sync; run `fabric instructions sync` then push again",
+        7
+      );
+    case "REPOSITORY_SOURCE_OF_TRUTH":
+      return new CliFailure(
+        "this project's coding instructions come from its repository, so they are changed there and mirrored into Fabric \u2014 commit and push to the repository instead; nothing was sent",
+        7
+      );
+    case "NOTHING_PUBLISHED":
+      return new CliFailure(
+        "this project has no published coding instructions to change yet; the first version is uploaded from the Coding Instructions tab",
+        4
+      );
+    case "PROPOSAL_PROPOSER_LIMIT":
+    case "PROPOSAL_PROJECT_LIMIT":
+      return new CliFailure(`${message} Nothing was sent.`, 7);
+    default:
+      return asCliFailure(error);
+  }
+}
+function pushVerdict(outcome) {
+  var _a2;
+  if (outcome.proposalStatus === "PENDING" && outcome.status === "RECEIVING") {
+    return `An earlier attempt is still sending this change; if version ${outcome.version} stays unfinished, cancel it in the project's Coding Instructions tab, or leave it and it is closed out automatically after six hours.`;
+  }
+  if (outcome.proposalStatus === "PENDING" && outcome.status === "FAILED") {
+    return `This proposal did not pass its checks; retry version ${outcome.version} from the project's Coding Instructions tab.`;
+  }
+  if (outcome.proposalStatus === "PENDING") {
+    if (outcome.status === "REJECTED") {
+      return `Version ${outcome.version} was rejected by its checks \u2014 cancel it in the project's Coding Instructions tab before proposing this change again.`;
+    }
+    return `Proposed as version ${outcome.version}. It is pending review \u2014 nothing is published until somebody who can edit this project's coding instructions approves it in the Coding Instructions tab.`;
+  }
+  if (outcome.proposalStatus === "APPROVED") {
+    return `Version ${outcome.version} has already been approved and published \u2014 run \`fabric instructions sync\` to bring this checkout up to it.`;
+  }
+  return `Version ${outcome.version} is no longer open for review (${(_a2 = outcome.proposalStatus) != null ? _a2 : outcome.status}): an earlier attempt at this same change was closed out, so push again.`;
+}
+function reportPush(outcome) {
+  const prefix = outcome.dryRun ? "Would send" : "Sent";
+  line(
+    `${prefix} ${outcome.put.length} changed file(s) and ${outcome.deleted.length} deletion(s) against version ${outcome.baseVersion} (${outcome.unchanged} unchanged).`
+  );
+  listPaths("changed", outcome.put);
+  listPaths("deleted", outcome.deleted);
+  if (outcome.dryRun) {
+    line(
+      "Nothing was sent. Without --dry-run this would open a proposal for review."
+    );
+    return;
+  }
+  line(pushVerdict(outcome));
+  line(
+    "Your lock was not changed: it still names the published version, which is what `fabric instructions sync` compares against."
+  );
+}
 function runInit(opts, format) {
   return __async(this, null, function* () {
     if (opts.tool !== "claude-code") {