archal 0.9.11 → 0.9.13

package/dist/index.cjs

@@ -86957,11 +86957,18 @@ function checksumDir(dir) {
   for (const entry of entries) {
     if (entry.name === MANIFEST_FILE2) continue;
     const p = (0, import_node_path51.join)(dir, entry.name);
+    const nameBytes = Buffer.from(entry.name, "utf8");
     if (entry.isDirectory()) {
-      hash2.update(`${entry.name}:dir:${checksumDir(p)}`);
+      const sub = checksumDir(p) ?? "";
+      const subBytes = Buffer.from(sub, "utf8");
+      hash2.update(`d:${nameBytes.length}:${sub ? subBytes.length : 0}:`);
+      hash2.update(nameBytes);
+      hash2.update(subBytes);
     } else {
-      hash2.update(`${entry.name}:`);
-      hash2.update((0, import_node_fs51.readFileSync)(p));
+      const content = (0, import_node_fs51.readFileSync)(p);
+      hash2.update(`f:${nameBytes.length}:${content.length}:`);
+      hash2.update(nameBytes);
+      hash2.update(content);
     }
   }
   return hash2.digest("hex");
@@ -86992,6 +86999,16 @@ function parseTargetFlag(value) {
 }
 
 // src/skills/installer.ts
+var ARCHAL_SKILL_PREFIX = "archal-";
+var SAFE_SKILL_NAME_RE = /^archal-[a-z0-9][a-z0-9-]*$/;
+function isSafeSkillName(destName) {
+  return SAFE_SKILL_NAME_RE.test(destName);
+}
+function isValidManifestEntry(value) {
+  if (!value || typeof value !== "object") return false;
+  const entry = value;
+  return typeof entry["checksum"] === "string" && typeof entry["version"] === "string";
+}
 var RESET8 = "\x1B[0m";
 var BOLD7 = "\x1B[1m";
 var DIM8 = "\x1B[2m";
@@ -87008,11 +87025,12 @@ async function runInstaller({
 }) {
   const log3 = silent ? () => {
   } : (msg) => process.stdout.write(msg);
+  const isNonInteractive = nonInteractive || !process.stdin.isTTY;
   const skillDirs = (0, import_node_fs52.readdirSync)(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   const selected = await resolveTargets({
     cwd,
     requested: requestedTargets ?? null,
-    nonInteractive,
+    nonInteractive: isNonInteractive,
     log: log3,
     version: version3
   });
@@ -87022,7 +87040,9 @@ async function runInstaller({
     return { installed: 0, targets: [], skipped: [], version: version3 };
   }
   let installed = 0;
+  let removed = 0;
   const skipped = [];
+  const sourceDestNames = new Set(skillDirs.map((s) => `${ARCHAL_SKILL_PREFIX}${s}`));
   for (const target of selected) {
     const platformDir = (0, import_node_path52.join)(cwd, target.skillsPath);
     (0, import_node_fs52.mkdirSync)(platformDir, { recursive: true });
@@ -87034,35 +87054,44 @@ async function runInstaller({
     };
     for (const skill of skillDirs) {
       const src = (0, import_node_path52.join)(skillsDir, skill);
-      const destName = `archal-${skill}`;
+      const destName = `${ARCHAL_SKILL_PREFIX}${skill}`;
       const dest = (0, import_node_path52.join)(platformDir, destName);
       const sourceChecksum = checksumDir(src);
       const existingChecksum = checksumDir(dest);
       const manifestEntry = manifest?.skills?.[destName];
-      const userEdited = existingChecksum && manifestEntry?.checksum && existingChecksum !== manifestEntry.checksum && existingChecksum !== sourceChecksum;
+      let userEdited = false;
+      let migrationCase = false;
+      if (existingChecksum) {
+        if (manifestEntry?.checksum) {
+          userEdited = existingChecksum !== manifestEntry.checksum && existingChecksum !== sourceChecksum;
+        } else if (existingChecksum !== sourceChecksum) {
+          userEdited = true;
+          migrationCase = true;
+        }
+      }
       if (userEdited && !yes) {
-        if (nonInteractive) {
-          skipped.push(`${target.id}/${destName} (user-edited, --yes required)`);
-          nextManifest.skills[destName] = {
-            version: manifestEntry?.version ?? "unknown",
-            checksum: existingChecksum,
-            userEdited: true
-          };
+        const message = migrationCase ? `${target.label}: ${destName} exists from an earlier install and may contain local edits. Overwrite with archal@${version3}?` : `${target.label}: ${destName} has local edits. Overwrite?`;
+        const skipSuffix = migrationCase ? "legacy install, --yes required" : "user-edited, --yes required";
+        const keptSuffix = migrationCase ? "kept legacy copy" : "kept user edits";
+        const preservedEntry = {
+          version: manifestEntry?.version ?? (migrationCase ? "legacy" : "unknown"),
+          checksum: manifestEntry?.checksum ?? sourceChecksum ?? "",
+          userEdited: true
+        };
+        if (isNonInteractive) {
+          skipped.push(`${target.id}/${destName} (${skipSuffix})`);
+          nextManifest.skills[destName] = preservedEntry;
           continue;
         }
         const { overwrite } = await (0, import_prompts.default)({
           type: "confirm",
           name: "overwrite",
-          message: `${target.label}: ${destName} has local edits. Overwrite?`,
-          initial: false
+          message,
+          initial: migrationCase ? true : false
         });
         if (!overwrite) {
-          skipped.push(`${target.id}/${destName} (kept user edits)`);
-          nextManifest.skills[destName] = {
-            version: manifestEntry?.version ?? "unknown",
-            checksum: existingChecksum,
-            userEdited: true
-          };
+          skipped.push(`${target.id}/${destName} (${keptSuffix})`);
+          nextManifest.skills[destName] = preservedEntry;
           continue;
         }
       }
@@ -87076,6 +87105,49 @@ async function runInstaller({
       };
       installed++;
     }
+    if (manifest?.skills) {
+      for (const [destName, rawEntry] of Object.entries(manifest.skills)) {
+        if (!isSafeSkillName(destName)) {
+          continue;
+        }
+        if (!isValidManifestEntry(rawEntry)) {
+          continue;
+        }
+        const entry = rawEntry;
+        if (sourceDestNames.has(destName)) continue;
+        const dest = (0, import_node_path52.join)(platformDir, destName);
+        if (!(0, import_node_fs52.existsSync)(dest)) continue;
+        const existingChecksum = checksumDir(dest);
+        const userEdited = existingChecksum !== entry.checksum;
+        if (userEdited && !yes) {
+          const preservedEntry = {
+            version: entry.version,
+            checksum: entry.checksum,
+            userEdited: true
+          };
+          if (isNonInteractive) {
+            skipped.push(
+              `${target.id}/${destName} (removed upstream, edits detected \u2014 --yes required)`
+            );
+            nextManifest.skills[destName] = preservedEntry;
+            continue;
+          }
+          const { remove } = await (0, import_prompts.default)({
+            type: "confirm",
+            name: "remove",
+            message: `${target.label}: ${destName} was removed upstream but has local edits. Delete it?`,
+            initial: false
+          });
+          if (!remove) {
+            skipped.push(`${target.id}/${destName} (kept local copy)`);
+            nextManifest.skills[destName] = preservedEntry;
+            continue;
+          }
+        }
+        (0, import_node_fs52.rmSync)(dest, { recursive: true, force: true });
+        removed++;
+      }
+    }
     writeManifest(platformDir, nextManifest);
   }
   const targetLabels = selected.map((t) => t.label).join(", ");
@@ -87084,6 +87156,10 @@ ${GREEN5}${BOLD7}Archal skills installed${RESET8} ${DIM8}(v${version3})${RESET8}
 `);
   log3(`${DIM8}${installed} skill(s) \u2192 ${targetLabels}${RESET8}
 `);
+  if (removed > 0) {
+    log3(`${DIM8}${removed} skill(s) removed (no longer shipped)${RESET8}
+`);
+  }
   if (skipped.length) {
     log3(`${YELLOW4}Skipped:${RESET8}
 `);
@@ -87143,7 +87219,7 @@ ${BOLD7}Install Archal skills${RESET8} ${DIM8}(v${version3})${RESET8}
       onCancel: () => {
         log3(`${YELLOW4}Cancelled.${RESET8}
 `);
-        process.exit(0);
+        process.exit(130);
       }
     }
   );
@@ -87155,11 +87231,27 @@ ${BOLD7}Install Archal skills${RESET8} ${DIM8}(v${version3})${RESET8}
 init_version();
 init_errors6();
 function detectPackageManager2(cwd) {
+  const fromPackageManager = readPackageManagerField(cwd);
+  if (fromPackageManager) return fromPackageManager;
   if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(cwd, "bun.lockb"))) return "bun";
+  if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(cwd, "bun.lockb")) || (0, import_node_fs53.existsSync)((0, import_node_path53.join)(cwd, "bun.lock"))) return "bun";
   if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(cwd, "yarn.lock"))) return "yarn";
   return "npm";
 }
+function readPackageManagerField(cwd) {
+  try {
+    const pkg = JSON.parse((0, import_node_fs53.readFileSync)((0, import_node_path53.join)(cwd, "package.json"), "utf8"));
+    const raw = typeof pkg.packageManager === "string" ? pkg.packageManager : "";
+    const name = raw.split("@")[0];
+    if (name === "pnpm" || name === "yarn" || name === "bun" || name === "npm") {
+      return name;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 function hasPackageJson(cwd) {
   return (0, import_node_fs53.existsSync)((0, import_node_path53.join)(cwd, "package.json"));
 }
@@ -87171,26 +87263,78 @@ function alreadyHasArchalDep(cwd) {
     return false;
   }
 }
+function looksLikeSkillsDir(candidate) {
+  if (!(0, import_node_fs53.existsSync)(candidate)) return false;
+  let entries;
+  try {
+    entries = (0, import_node_fs53.readdirSync)(candidate);
+  } catch {
+    return false;
+  }
+  for (const name of entries) {
+    const child = (0, import_node_path53.join)(candidate, name);
+    try {
+      if (!(0, import_node_fs53.statSync)(child).isDirectory()) continue;
+      if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(child, "SKILL.md"))) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function findPnpmWorkspaceRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 10; i++) {
+    if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(dir, "pnpm-workspace.yaml"))) return dir;
+    const parent = (0, import_node_path53.dirname)(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+function findRepoRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 10; i++) {
+    if ((0, import_node_fs53.existsSync)((0, import_node_path53.join)(dir, "pnpm-workspace.yaml"))) return dir;
+    const parent = (0, import_node_path53.dirname)(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
 function resolveSkillsDir() {
   const here = typeof __dirname === "string" ? __dirname : process.cwd();
+  const repoRoot = findRepoRoot(here) ?? findRepoRoot(process.cwd());
   const candidates = [
     (0, import_node_path53.resolve)(here, "..", "skills"),
-    (0, import_node_path53.resolve)(here, "..", "..", "..", "packages", "archal-skills", "skills"),
-    (0, import_node_path53.resolve)(process.cwd(), "packages", "archal-skills", "skills")
+    ...repoRoot ? [(0, import_node_path53.resolve)(repoRoot, "packages", "archal", "skills")] : [],
+    (0, import_node_path53.resolve)(process.cwd(), "packages", "archal", "skills"),
+    (0, import_node_path53.resolve)(process.cwd(), "skills")
   ];
   for (const candidate of candidates) {
-    if ((0, import_node_fs53.existsSync)(candidate)) return candidate;
+    if (looksLikeSkillsDir(candidate)) return candidate;
   }
   throw new CliRuntimeError(
-    "Could not locate the Archal skills directory. Reinstall archal, or run `npx @archal/skills` directly."
+    "Could not locate the Archal skills directory. This looks like a broken archal install \u2014 reinstall with `npm install archal` (or your package manager equivalent) and retry."
   );
 }
 function runPmAdd(pm, cwd, spec) {
-  const args = pm === "npm" ? ["install", "--save-dev", spec] : ["add", "-D", spec];
+  let args;
+  if (pm === "npm") {
+    args = ["install", "--save-dev", "--no-audit", "--no-fund", "--loglevel=error", spec];
+  } else if (pm === "pnpm" && findPnpmWorkspaceRoot(cwd) === cwd) {
+    args = ["add", "-D", "-w", spec];
+  } else {
+    args = ["add", "-D", spec];
+  }
   const result = (0, import_node_child_process10.spawnSync)(pm, args, { cwd, stdio: "inherit" });
+  if (result.error) {
+    throw new CliRuntimeError(
+      `Failed to launch ${pm}: ${result.error.message}. Install ${pm} (or install \`archal\` manually) and re-run \`archal init\`.`
+    );
+  }
   if (result.status !== 0) {
     throw new CliRuntimeError(
-      `Failed to install ${spec} with ${pm}. Install manually and re-run \`archal init\`.`
+      `Failed to install ${spec} with ${pm} (exit ${result.status}). Install manually and re-run \`archal init\`.`
     );
   }
 }
@@ -87209,29 +87353,71 @@ function createInitCommand() {
           throw new CliRuntimeError(err instanceof Error ? err.message : String(err));
         }
       }
-      if (!opts.skillsOnly) {
-        if (!hasPackageJson(cwd)) {
-          process.stderr.write(
-            "No package.json in cwd \u2014 skipping devDependency install. Install archal globally (`npm i -g archal`) or initialize a package.json first.\n"
-          );
-        } else if (alreadyHasArchalDep(cwd)) {
-          process.stdout.write(`archal already a dependency \u2014 skipping install.
+      let cliInstalled = true;
+      const hadPackageJson = hasPackageJson(cwd);
+      const startedAt = Date.now();
+      try {
+        if (!opts.skillsOnly) {
+          if (!SEMVER_RE.test(CLI_VERSION)) {
+            throw new CliRuntimeError(
+              `Invalid CLI_VERSION "${CLI_VERSION}" \u2014 refusing to install. Reinstall archal and retry.`
+            );
+          }
+          if (!hadPackageJson) {
+            process.stderr.write(
+              "No package.json in cwd \u2014 skipping devDependency install. Install archal globally (`npm i -g archal`) or initialize a package.json first.\n"
+            );
+            cliInstalled = false;
+          } else if (alreadyHasArchalDep(cwd)) {
+            process.stdout.write(`archal already a dependency \u2014 skipping install.
 `);
-        } else {
-          const pm = detectPackageManager2(cwd);
-          process.stdout.write(`Installing archal@${CLI_VERSION} with ${pm}\u2026
+          } else {
+            const pm = detectPackageManager2(cwd);
+            process.stdout.write(`Installing archal@${CLI_VERSION} with ${pm}\u2026
 `);
-          runPmAdd(pm, cwd, `archal@${CLI_VERSION}`);
+            runPmAdd(pm, cwd, `archal@${CLI_VERSION}`);
+          }
+        } else {
+          cliInstalled = alreadyHasArchalDep(cwd);
+        }
+        const result = await runInstaller({
+          cwd,
+          targets: targets ?? void 0,
+          nonInteractive: opts.nonInteractive === true,
+          yes: opts.yes === true,
+          skillsDir: resolveSkillsDir(),
+          version: CLI_VERSION
+        });
+        if (opts.skillsOnly && !cliInstalled) {
+          process.stdout.write(
+            `Note: --skills-only left out the archal runner. Run \`npm install -D archal\` (or pnpm / yarn / bun equivalent) before \`archal run\`.
+`
+          );
         }
+        captureCliEvent("cli_init_completed", {
+          skills_only: Boolean(opts.skillsOnly),
+          non_interactive: opts.nonInteractive === true,
+          yes: opts.yes === true,
+          target_count: result.targets.length,
+          targets: result.targets,
+          installed: result.installed,
+          skipped: result.skipped.length,
+          had_package_json: hadPackageJson,
+          cli_installed: cliInstalled,
+          duration_ms: Date.now() - startedAt
+        });
+      } catch (err) {
+        captureCliEvent("cli_init_failed", {
+          skills_only: Boolean(opts.skillsOnly),
+          non_interactive: opts.nonInteractive === true,
+          yes: opts.yes === true,
+          had_package_json: hadPackageJson,
+          error_name: err instanceof Error ? err.constructor.name : "Unknown",
+          error_message: err instanceof Error ? err.message : String(err),
+          duration_ms: Date.now() - startedAt
+        });
+        throw err;
       }
-      await runInstaller({
-        cwd,
-        targets: targets ?? void 0,
-        nonInteractive: opts.nonInteractive === true,
-        yes: opts.yes === true,
-        skillsDir: resolveSkillsDir(),
-        version: CLI_VERSION
-      });
     }
   );
 }
@@ -87359,6 +87545,20 @@ function readManifestAt(path2) {
     return null;
   }
 }
+function compareSemver(a, b) {
+  const parse3 = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?$/.exec(v);
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+  };
+  const pa = parse3(a);
+  const pb = parse3(b);
+  if (!pa || !pb) return null;
+  if (pa[0] !== pb[0]) return pa[0] - pb[0];
+  if (pa[1] !== pb[1]) return pa[1] - pb[1];
+  if (pa[2] !== pb[2]) return pa[2] - pb[2];
+  return 0;
+}
 function maybePrintSkillDriftBanner(cwd = process.cwd()) {
   try {
     const stale = [];
@@ -87367,7 +87567,8 @@ function maybePrintSkillDriftBanner(cwd = process.cwd()) {
       if (!(0, import_node_fs55.existsSync)(manifestPath)) continue;
       const manifest = readManifestAt(manifestPath);
       if (!manifest?.version) continue;
-      if (manifest.version !== CLI_VERSION) {
+      const cmp = compareSemver(manifest.version, CLI_VERSION);
+      if (cmp !== null && cmp < 0) {
         stale.push(`${target.label} (v${manifest.version})`);
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archal",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Test your agents & integrations against digital twins",
   "type": "module",
   "main": "dist/index.cjs",
@@ -45,8 +45,13 @@
     "twin-assets",
     "LICENSE"
   ],
-  "dependencies": {
-    "vitest": "^2.1.0"
+  "peerDependencies": {
+    "vitest": ">=2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
   },
   "scripts": {
     "verify:artifacts": "node scripts/assert-artifacts.mjs",

package/skills/onboard/SKILL.md

@@ -8,6 +8,19 @@ user-invocable: true
 
 You are setting up Archal in this project. Archal tests AI agents against digital twins of real services (GitHub, Slack, Stripe, etc.). Handle installation and auth yourself; delegate the workflow-specific setup to the matching sub-skill.
 
+## If this is a cold-start
+
+The user may have landed here without running `npx archal init` first. If the
+CLI is missing (see "Install + auth" below) AND no `.archal-manifest.json`
+exists in `.claude/skills/`, the canonical first command is:
+
+```bash
+npx archal init
+```
+
+That adds `archal` as a devDependency and reinstalls these skills at the
+right version. Re-invoke the onboard skill after it completes.
+
 ## Discover first
 
 Before asking anything, read the repo:
@@ -25,14 +38,23 @@ Before asking anything, read the repo:
 
 ## Install + auth
 
+If you're here via `npx archal init`, archal is already a devDependency
+and the skills are already in place. Go straight to login:
+
 ```bash
-npx archal --version        # check if installed
-npm install -D archal       # install if not (or -g for global)
-archal usage                # check auth
 archal login                # OAuth browser flow, or: archal login --token <token>
+archal usage                # verify auth + plan
 ```
 
-In CI, use `ARCHAL_TOKEN` instead of `archal login`.
+In CI, set `ARCHAL_TOKEN` instead of running `archal login`.
+
+If something feels wrong (missing CLI, stale skills), these are the
+recovery commands — don't run them otherwise:
+
+```bash
+npx archal --version           # CLI reachable? prints e.g. 0.9.12
+npx archal init --skills-only  # re-stage skills if they drifted
+```
 
 ## Pick a workflow
 

package/skills/scenario/SKILL.md

@@ -99,6 +99,8 @@ Aliases for `evaluator-model`: `evaluator`, `evaluatormodel`, `model`.
 | `supabase` | `empty`, `small-project`, `saas-starter`, `ecommerce` |
 | `google-workspace` | `empty`, `assistant-baseline`, `gmail-busy-inbox`, `calendar-packed-week` |
 | `ramp` | `empty`, `default` |
+| `discord` | `empty`, `small-server`, `harvested` |
+| `telegram` | `empty`, `harvested` |
 
 ## Twin auto-detection from content
 
@@ -111,6 +113,12 @@ If no `twins:` config is set, Archal infers twins from keywords in Setup, Expect
 - `stripe`, `payment`, `refund`, `subscription`, `invoice` -> `stripe`
 - `supabase`, `database`, `sql query` -> `supabase`
 - `google workspace`, `gmail`, `calendar event`, `inbox` -> `google-workspace`
+- `discord`, `guild`, `text channel` -> `discord`
+
+Not every twin has auto-detect keywords — `telegram` in particular has
+none. If your scenario uses `telegram`, set `twins: telegram` in the
+Config block or in `.archal.json`. `ramp` auto-detects on `ramp`,
+`bill`, `expense`, `reimbursement`, `fund`, `card spend`.
 
 ## Multi-service scenarios
 

package/twin-assets/google-workspace/tools.json

@@ -13,7 +13,8 @@
           },
           "refresh_token": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "maxLength": 2048
           },
           "client_id": {
             "type": "string"