@kelceyp/caw 1.0.42 → 1.0.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +44 -1
  2. package/dist/caw.js +137 -104
  3. package/package.json +1 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # CAW
2
2
 
3
- CAW helps users build software **sustainably** using AI by providing agents with **C**ontext and **A**gentic **W**orkflows (CAW). CAW is free to download and runs locally as a unified web and MCP server. It provides document management, templates, stories, search and acts as the orchestration layer for your AI development tools.
3
+ CAW helps users build software **sustainably** using AI by providing agents with **C**ontext and **A**gentic **W**orkflows (CAW). CAW is free to download and runs locally as a unified web and MCP server. It provides document management, templates, stories, search and acts as the orchestration layer for your AI development tools. CAW itself reaches out to PostHog for [usage analytics](#usage-analytics), the npm registry, `athenadesign.com.au` for its bundle catalogue and bundles, and Hugging Face to download its embedding model; the agents you run talk to their own vendors.
4
4
 
5
5
  ![CAW overview](https://athenadesign.com.au/caw/animation.svg)
6
6
 
@@ -21,6 +21,49 @@ caw start
21
21
  ```
22
22
  Then open [http://localhost:2229](http://localhost:2229) in your browser.
23
23
 
24
+ Requires macOS and Node.js 24 or later. If the install or `caw start` fails, see the [installation guide](https://athenadesign.com.au/caw/installation-guide).
25
+
26
+ ## Usage analytics
27
+
28
+ CAW sends timestamped usage events to [PostHog](https://posthog.com) (US) by default. They are keyed to a random install ID. There is no account, and the ID isn't derived from anything about you or your machine.
29
+
30
+ Installing sends no events. On a new install, with no `config.json`, the first event is sent when `caw start` or `caw restart` starts the server, whether or not that start then succeeds, and CAW prints a one-time notice just before it. On an existing install, or with a `config.json` you wrote yourself that doesn't turn analytics off, `caw stop`, `caw upgrade` and `caw caddy setup` can also send an event or start a server that does, and they print no notice.
31
+
32
+ | Event | Sent by | Carries |
33
+ |---|---|---|
34
+ | `caw cmd` | launcher | `op` (start or stop); on start, also launcher version, OS and architecture |
35
+ | `project op` | server | `op` (created or deleted) |
36
+ | `agent toggled` | server | `agent`, `op` |
37
+ | `infra toggled` | server | `infra`, `op` |
38
+ | `mcp first call` | server | `agent` |
39
+ | `story op` | server | `op`; on completion, the number of states |
40
+ | `job turn completed` | server | start and end times, `agent`, `mechanism`, whether a working directory was set and whether Docker was used, `effort`, `model`, `exit_code`, `error_category` and a hash of the story ID, keyed with a salt that stays on your machine |
41
+ | `analytics opted_out` | server | `via` |
42
+ | `analytics opted_in` | server | `via` |
43
+
44
+ The server also identifies itself with its CAW version, OS and architecture, and its events can carry `channel` (how the action arrived) and `caller_bucket` (which kind of agent made it). PostHog's client library adds its own name and version, and marks each event as sent from a server. Preferences > Analytics lists the events of the server you're running, which may be newer than this page.
45
+
46
+ **Never sent:** document, story, template or prompt content, titles, filesystem paths, search queries, tool arguments or repo URLs.
47
+
48
+ PostHog receives the IP address of each request, as any server does. The CAW PostHog project is set to discard it rather than store it with events, and every event CAW sends asks PostHog not to look up a location from it.
49
+
50
+ ### Turning it off
51
+
52
+ - **Preferences > Analytics:** takes effect immediately, and sends one final `analytics opted_out` event.
53
+ - **`"analyticsEnabled": false` in `~/.caw/config.json`:** the launcher stops sending at once. A running server stops at its next start, so run `caw restart`. No final event is sent.
54
+
55
+ The value must be a JSON boolean. `caw start` silently replaces `"false"`, a string, with `true`.
56
+
57
+ ### Turning it off before the first start
58
+
59
+ On a machine where CAW has never started, run this before `caw start`. Don't run it on an existing install, because it overwrites `config.json`.
60
+
61
+ ```bash
62
+ mkdir -p ~/.caw && echo '{"port":2229,"process_manager":"pid","caddy":{"enabled":false,"domain":"caw.localhost"},"analyticsEnabled":false}' > ~/.caw/config.json && touch ~/.caw/.env
63
+ ```
64
+
65
+ CAW then starts with analytics off: it sends no events and prints no notice.
66
+
24
67
  ## Unlock sustainable development
25
68
  Agents are capable coders but struggle to build software sustainably as the codebase and its complexity grow. Code reveals only so much and agents do not inherently know which parts of it to read or what the underlying intent was. Technical debt, technical mess, architectural mismatch and a host of problems creep in over time to grind progress to a halt.
26
69
 
package/dist/caw.js CHANGED
@@ -10879,8 +10879,8 @@ function resolve(overrideBinPath) {
10879
10879
  }
10880
10880
 
10881
10881
  // src/commands/start.js
10882
- import fs8 from "node:fs";
10883
- import path9 from "node:path";
10882
+ import fs9 from "node:fs";
10883
+ import path10 from "node:path";
10884
10884
  import os2 from "node:os";
10885
10885
  import crypto3 from "node:crypto";
10886
10886
  import { execSync as execSync4 } from "node:child_process";
@@ -11481,7 +11481,7 @@ async function emitCawCmd({ op, config }) {
11481
11481
  if (apiKey === null)
11482
11482
  return;
11483
11483
  const host = process.env.POSTHOG_HOST || DEFAULT_HOST;
11484
- const properties = { op };
11484
+ const properties = { op, $geoip_disable: true };
11485
11485
  if (op === "start") {
11486
11486
  properties.$set = {
11487
11487
  launcher_version: launcherVersion(),
@@ -11521,18 +11521,44 @@ async function emitCawCmdStop({ config }) {
11521
11521
  return emitCawCmd({ op: "stop", config });
11522
11522
  }
11523
11523
 
11524
+ // src/analytics-notice.js
11525
+ import fs6 from "node:fs";
11526
+ import path7 from "node:path";
11527
+ var MARKER_FILENAME = "analytics-notice-shown";
11528
+ function noticeText(envDir) {
11529
+ return [
11530
+ "CAW sends usage analytics to PostHog. This is on by default.",
11531
+ `To turn it off, use Preferences > Analytics, or set "analyticsEnabled": false in ${path7.join(envDir, "config.json")}.`,
11532
+ "What is sent and what isn't: https://www.npmjs.com/package/@kelceyp/caw"
11533
+ ].join(`
11534
+ `);
11535
+ }
11536
+ function showAnalyticsNoticeOnce({ envDir }) {
11537
+ if (readConfig(envDir).analyticsEnabled === false) {
11538
+ return;
11539
+ }
11540
+ const markerPath = path7.join(envDir, MARKER_FILENAME);
11541
+ if (fs6.existsSync(markerPath)) {
11542
+ return;
11543
+ }
11544
+ console.log(noticeText(envDir));
11545
+ try {
11546
+ fs6.closeSync(fs6.openSync(markerPath, "a"));
11547
+ } catch {}
11548
+ }
11549
+
11524
11550
  // src/first-run-install.js
11525
- import fs7 from "node:fs";
11526
- import path8 from "node:path";
11551
+ import fs8 from "node:fs";
11552
+ import path9 from "node:path";
11527
11553
  import crypto2 from "node:crypto";
11528
11554
 
11529
11555
  // src/bundle-install-lock.js
11530
- import fs6 from "node:fs";
11531
- import path7 from "node:path";
11556
+ import fs7 from "node:fs";
11557
+ import path8 from "node:path";
11532
11558
  var LOCK_FILENAME = "config.bundle-install.lock";
11533
11559
  var STALE_LOCK_MS = 1e4;
11534
11560
  function lockPathFor2(envDir) {
11535
- return path7.join(envDir, LOCK_FILENAME);
11561
+ return path8.join(envDir, LOCK_FILENAME);
11536
11562
  }
11537
11563
  function makeReleaser(lockPath) {
11538
11564
  let released = false;
@@ -11541,31 +11567,31 @@ function makeReleaser(lockPath) {
11541
11567
  return;
11542
11568
  released = true;
11543
11569
  try {
11544
- fs6.unlinkSync(lockPath);
11570
+ fs7.unlinkSync(lockPath);
11545
11571
  } catch {}
11546
11572
  };
11547
11573
  }
11548
11574
  var NOOP_RELEASE = () => {};
11549
11575
  function acquire({ envDir }) {
11550
- fs6.mkdirSync(envDir, { recursive: true });
11576
+ fs7.mkdirSync(envDir, { recursive: true });
11551
11577
  const lockPath = lockPathFor2(envDir);
11552
11578
  try {
11553
- const fd = fs6.openSync(lockPath, "wx");
11554
- fs6.closeSync(fd);
11579
+ const fd = fs7.openSync(lockPath, "wx");
11580
+ fs7.closeSync(fd);
11555
11581
  return { acquired: true, release: makeReleaser(lockPath) };
11556
11582
  } catch (e) {
11557
11583
  if (e.code !== "EEXIST")
11558
11584
  throw e;
11559
11585
  }
11560
11586
  try {
11561
- const st = fs6.statSync(lockPath);
11587
+ const st = fs7.statSync(lockPath);
11562
11588
  if (Date.now() - st.mtimeMs > STALE_LOCK_MS) {
11563
11589
  try {
11564
- fs6.unlinkSync(lockPath);
11590
+ fs7.unlinkSync(lockPath);
11565
11591
  } catch {}
11566
11592
  try {
11567
- const fd = fs6.openSync(lockPath, "wx");
11568
- fs6.closeSync(fd);
11593
+ const fd = fs7.openSync(lockPath, "wx");
11594
+ fs7.closeSync(fd);
11569
11595
  return { acquired: true, release: makeReleaser(lockPath) };
11570
11596
  } catch {}
11571
11597
  }
@@ -11703,10 +11729,10 @@ function resolveFetch(out) {
11703
11729
  return out && typeof out.fetch === "function" ? out.fetch : fetch;
11704
11730
  }
11705
11731
  function stagedZipPath(envDir, name) {
11706
- return path8.join(envDir, SHARED_EXPORTS_DIR, `${name}.zip`);
11732
+ return path9.join(envDir, SHARED_EXPORTS_DIR, `${name}.zip`);
11707
11733
  }
11708
11734
  function sha256File(filePath) {
11709
- return crypto2.createHash("sha256").update(fs7.readFileSync(filePath)).digest("hex");
11735
+ return crypto2.createHash("sha256").update(fs8.readFileSync(filePath)).digest("hex");
11710
11736
  }
11711
11737
  async function fetchInfo(port, fetchFn) {
11712
11738
  const controller = new AbortController;
@@ -11733,8 +11759,8 @@ async function downloadTo(url, targetPath, fetchFn) {
11733
11759
  throw new Error(`download: HTTP ${res.status} for ${url}`);
11734
11760
  }
11735
11761
  const buf = Buffer.from(await res.arrayBuffer());
11736
- fs7.mkdirSync(path8.dirname(targetPath), { recursive: true });
11737
- fs7.writeFileSync(targetPath, buf);
11762
+ fs8.mkdirSync(path9.dirname(targetPath), { recursive: true });
11763
+ fs8.writeFileSync(targetPath, buf);
11738
11764
  }
11739
11765
  async function postImport(port, filename, fetchFn) {
11740
11766
  const url = `http://localhost:${port}/api/shared/bundle/import`;
@@ -11768,19 +11794,19 @@ async function postImport(port, filename, fetchFn) {
11768
11794
  function filenameFromCatalogueEntry(entry, name) {
11769
11795
  try {
11770
11796
  const u = new URL(entry.url);
11771
- const base = path8.basename(u.pathname);
11797
+ const base = path9.basename(u.pathname);
11772
11798
  return base && base.length > 0 ? base : `${name}.zip`;
11773
11799
  } catch {
11774
11800
  return `${name}.zip`;
11775
11801
  }
11776
11802
  }
11777
11803
  async function ensureLocalBundleFile({ envDir, name, entry, fetchFn }) {
11778
- const sharedDir = path8.join(envDir, SHARED_EXPORTS_DIR);
11779
- fs7.mkdirSync(sharedDir, { recursive: true });
11804
+ const sharedDir = path9.join(envDir, SHARED_EXPORTS_DIR);
11805
+ fs8.mkdirSync(sharedDir, { recursive: true });
11780
11806
  if (entry) {
11781
11807
  const filename = filenameFromCatalogueEntry(entry, name);
11782
- const filePath = path8.join(sharedDir, filename);
11783
- let needDownload = !fs7.existsSync(filePath);
11808
+ const filePath = path9.join(sharedDir, filename);
11809
+ let needDownload = !fs8.existsSync(filePath);
11784
11810
  if (!needDownload && entry.sha256) {
11785
11811
  try {
11786
11812
  if (sha256File(filePath) !== entry.sha256)
@@ -11803,7 +11829,7 @@ async function ensureLocalBundleFile({ envDir, name, entry, fetchFn }) {
11803
11829
  return { filename, sourceSha256: entry.sha256 };
11804
11830
  }
11805
11831
  const stagedPath = stagedZipPath(envDir, name);
11806
- if (!fs7.existsSync(stagedPath)) {
11832
+ if (!fs8.existsSync(stagedPath)) {
11807
11833
  const err = new Error(`no staged zip at ${stagedPath}`);
11808
11834
  err.__outcome = OUTCOME.NOT_FOUND;
11809
11835
  throw err;
@@ -11974,20 +12000,20 @@ var __test__2 = Object.freeze({ OUTCOME, INFO_TIMEOUT_MS, SHARED_EXPORTS_DIR });
11974
12000
  // src/commands/start.js
11975
12001
  function resolveEnvDir(rawEnvDir) {
11976
12002
  if (rawEnvDir.startsWith("~")) {
11977
- rawEnvDir = path9.join(os2.homedir(), rawEnvDir.slice(1));
12003
+ rawEnvDir = path10.join(os2.homedir(), rawEnvDir.slice(1));
11978
12004
  }
11979
- return path9.resolve(rawEnvDir);
12005
+ return path10.resolve(rawEnvDir);
11980
12006
  }
11981
12007
  function validateEnvFile(envDir) {
11982
- const envFilePath = path9.join(envDir, ".env");
11983
- if (!fs8.existsSync(envFilePath)) {
12008
+ const envFilePath = path10.join(envDir, ".env");
12009
+ if (!fs9.existsSync(envFilePath)) {
11984
12010
  return {
11985
12011
  ok: false,
11986
12012
  message: `Error: Environment file not found: ${envFilePath}
11987
12013
  Create it with your configuration variables (e.g., CLAUDE_CODE_OAUTH_TOKEN).`
11988
12014
  };
11989
12015
  }
11990
- const content = fs8.readFileSync(envFilePath, "utf8");
12016
+ const content = fs9.readFileSync(envFilePath, "utf8");
11991
12017
  const lines = content.split(`
11992
12018
  `);
11993
12019
  for (let i = 0;i < lines.length; i++) {
@@ -12009,10 +12035,10 @@ var MAX_LOG_SIZE = 10 * 1024 * 1024;
12009
12035
  var LOG_RETAIN = 5;
12010
12036
  function rotateLogIfNeeded(envDir) {
12011
12037
  try {
12012
- const logPath = path9.join(envDir, "server.log");
12013
- if (!fs8.existsSync(logPath))
12038
+ const logPath = path10.join(envDir, "server.log");
12039
+ if (!fs9.existsSync(logPath))
12014
12040
  return;
12015
- const stats = fs8.statSync(logPath);
12041
+ const stats = fs9.statSync(logPath);
12016
12042
  if (stats.size <= MAX_LOG_SIZE)
12017
12043
  return;
12018
12044
  const now = new Date;
@@ -12026,18 +12052,18 @@ function rotateLogIfNeeded(envDir) {
12026
12052
  pad2(now.getMinutes()),
12027
12053
  pad2(now.getSeconds())
12028
12054
  ].join("-");
12029
- fs8.renameSync(logPath, `${logPath}.${timestamp}`);
12055
+ fs9.renameSync(logPath, `${logPath}.${timestamp}`);
12030
12056
  console.log(`Rotated server.log (was ${(stats.size / 1024 / 1024).toFixed(1)} MB)`);
12031
- const rotated = fs8.readdirSync(envDir).filter((f) => f.startsWith("server.log.")).map((f) => ({ name: f, mtime: fs8.statSync(path9.join(envDir, f)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
12057
+ const rotated = fs9.readdirSync(envDir).filter((f) => f.startsWith("server.log.")).map((f) => ({ name: f, mtime: fs9.statSync(path10.join(envDir, f)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
12032
12058
  for (const file of rotated.slice(LOG_RETAIN)) {
12033
- fs8.unlinkSync(path9.join(envDir, file.name));
12059
+ fs9.unlinkSync(path10.join(envDir, file.name));
12034
12060
  }
12035
12061
  } catch (err) {
12036
12062
  console.warn(`Warning: log rotation failed: ${err.message}`);
12037
12063
  }
12038
12064
  }
12039
12065
  function buildEnvNodeArgs(envDir) {
12040
- const envFilePath = path9.join(envDir, ".env");
12066
+ const envFilePath = path10.join(envDir, ".env");
12041
12067
  return [`--env-file=${envFilePath}`];
12042
12068
  }
12043
12069
  function buildServerEnvVars(activeConfig, envDir) {
@@ -12058,7 +12084,7 @@ function ensureInstallIdentity(envDir) {
12058
12084
  if (hasFullIdentity(existing))
12059
12085
  return existing;
12060
12086
  }
12061
- fs8.mkdirSync(envDir, { recursive: true });
12087
+ fs9.mkdirSync(envDir, { recursive: true });
12062
12088
  return identity_lock_default.withIdentityLock({
12063
12089
  envDir,
12064
12090
  section: (lock) => {
@@ -12082,12 +12108,12 @@ function ensureInstallIdentity(envDir) {
12082
12108
  });
12083
12109
  }
12084
12110
  function bootstrap(envDir) {
12085
- fs8.mkdirSync(envDir, { recursive: true });
12086
- fs8.mkdirSync(path9.join(envDir, "assets"), { recursive: true });
12111
+ fs9.mkdirSync(envDir, { recursive: true });
12112
+ fs9.mkdirSync(path10.join(envDir, "assets"), { recursive: true });
12087
12113
  ensureInstallIdentity(envDir);
12088
- const envFilePath = path9.join(envDir, ".env");
12089
- if (!fs8.existsSync(envFilePath)) {
12090
- fs8.writeFileSync(envFilePath, [
12114
+ const envFilePath = path10.join(envDir, ".env");
12115
+ if (!fs9.existsSync(envFilePath)) {
12116
+ fs9.writeFileSync(envFilePath, [
12091
12117
  "# CAW environment configuration",
12092
12118
  "# Uncomment and set values as needed",
12093
12119
  "",
@@ -12206,6 +12232,7 @@ How would you like to proceed?`,
12206
12232
  await runFirstRunInstall({ envDir, config, port: config.port, out: undefined });
12207
12233
  process.exit(0);
12208
12234
  }
12235
+ showAnalyticsNoticeOnce({ envDir });
12209
12236
  await emitCawCmdStart({ config: readConfig(envDir) });
12210
12237
  let activeConfig = config;
12211
12238
  if (hasPendingConfig(envDir)) {
@@ -12251,7 +12278,7 @@ How would you like to proceed?`,
12251
12278
  const started = await pollHealth(activeConfig.port);
12252
12279
  if (!started) {
12253
12280
  console.error(`Server did not become healthy within 10 seconds.`);
12254
- console.error(`Check logs with: caw logs${envDir !== path9.join(os2.homedir(), ".caw") ? ` --env-dir ${envDir}` : ""}`);
12281
+ console.error(`Check logs with: caw logs${envDir !== path10.join(os2.homedir(), ".caw") ? ` --env-dir ${envDir}` : ""}`);
12255
12282
  process.exit(1);
12256
12283
  }
12257
12284
  console.log(`Server started successfully on http://localhost:${activeConfig.port}`);
@@ -12261,14 +12288,14 @@ How would you like to proceed?`,
12261
12288
  var start_default = Object.freeze({ create: create2 });
12262
12289
 
12263
12290
  // src/commands/stop.js
12264
- import fs9 from "node:fs";
12265
- import path10 from "node:path";
12291
+ import fs10 from "node:fs";
12292
+ import path11 from "node:path";
12266
12293
  import os3 from "node:os";
12267
12294
  function resolveEnvDir2(rawEnvDir) {
12268
12295
  if (rawEnvDir.startsWith("~")) {
12269
- rawEnvDir = path10.join(os3.homedir(), rawEnvDir.slice(1));
12296
+ rawEnvDir = path11.join(os3.homedir(), rawEnvDir.slice(1));
12270
12297
  }
12271
- return path10.resolve(rawEnvDir);
12298
+ return path11.resolve(rawEnvDir);
12272
12299
  }
12273
12300
  async function checkHealth2(port) {
12274
12301
  try {
@@ -12338,7 +12365,7 @@ var create3 = () => {
12338
12365
  return createCommand("stop").summary("Stop the caw server").param((p) => p.name("env-dir").type("string").flag("env-dir").default("~/.caw/")).param((p) => p.name("force").type("boolean").flag("force").default(false)).run(async (ctx) => {
12339
12366
  const envDir = resolveEnvDir2(ctx.params["env-dir"]);
12340
12367
  const force = ctx.params.force;
12341
- if (!fs9.existsSync(envDir) || !configExists(envDir)) {
12368
+ if (!fs10.existsSync(envDir) || !configExists(envDir)) {
12342
12369
  console.log("Server is not running (no environment directory or config found).");
12343
12370
  process.exit(0);
12344
12371
  }
@@ -12359,13 +12386,13 @@ var stop_default = Object.freeze({ create: create3 });
12359
12386
 
12360
12387
  // src/commands/status.js
12361
12388
  var import_semver = __toESM(require_semver2(), 1);
12362
- import fs11 from "node:fs";
12363
- import path12 from "node:path";
12389
+ import fs12 from "node:fs";
12390
+ import path13 from "node:path";
12364
12391
  import os4 from "node:os";
12365
12392
 
12366
12393
  // src/registry.js
12367
- import fs10 from "node:fs";
12368
- import path11 from "node:path";
12394
+ import fs11 from "node:fs";
12395
+ import path12 from "node:path";
12369
12396
  var CACHE_FILENAME = "caw-cache.json";
12370
12397
  var DEFAULT_TIMEOUT_MS = 1e4;
12371
12398
  var DEFAULT_TTL_MS = 60 * 60 * 1000;
@@ -12381,18 +12408,18 @@ async function fetchLatestVersion(packageName, { timeoutMs = DEFAULT_TIMEOUT_MS
12381
12408
  return data["dist-tags"].latest;
12382
12409
  }
12383
12410
  function readCache(envDir) {
12384
- const cachePath = path11.join(envDir, CACHE_FILENAME);
12411
+ const cachePath = path12.join(envDir, CACHE_FILENAME);
12385
12412
  try {
12386
- return JSON.parse(fs10.readFileSync(cachePath, "utf8"));
12413
+ return JSON.parse(fs11.readFileSync(cachePath, "utf8"));
12387
12414
  } catch {
12388
12415
  return null;
12389
12416
  }
12390
12417
  }
12391
12418
  function writeCache(envDir, cache) {
12392
- const cachePath = path11.join(envDir, CACHE_FILENAME);
12419
+ const cachePath = path12.join(envDir, CACHE_FILENAME);
12393
12420
  const tmp = cachePath + ".tmp";
12394
- fs10.writeFileSync(tmp, JSON.stringify(cache, null, 2));
12395
- fs10.renameSync(tmp, cachePath);
12421
+ fs11.writeFileSync(tmp, JSON.stringify(cache, null, 2));
12422
+ fs11.renameSync(tmp, cachePath);
12396
12423
  }
12397
12424
  function isCacheStale(cache, ttlMs = DEFAULT_TTL_MS) {
12398
12425
  if (!cache)
@@ -12409,9 +12436,9 @@ function isCacheStale(cache, ttlMs = DEFAULT_TTL_MS) {
12409
12436
  // src/commands/status.js
12410
12437
  function resolveEnvDir3(rawEnvDir) {
12411
12438
  if (rawEnvDir.startsWith("~")) {
12412
- rawEnvDir = path12.join(os4.homedir(), rawEnvDir.slice(1));
12439
+ rawEnvDir = path13.join(os4.homedir(), rawEnvDir.slice(1));
12413
12440
  }
12414
- return path12.resolve(rawEnvDir);
12441
+ return path13.resolve(rawEnvDir);
12415
12442
  }
12416
12443
  async function fetchHealth(port) {
12417
12444
  try {
@@ -12454,7 +12481,7 @@ function formatUptime(ms) {
12454
12481
  function getUptimeFromPidFile(envDir) {
12455
12482
  const filePath = pidFilePath(envDir);
12456
12483
  try {
12457
- const stat = fs11.statSync(filePath);
12484
+ const stat = fs12.statSync(filePath);
12458
12485
  return Date.now() - stat.mtimeMs;
12459
12486
  } catch {
12460
12487
  return null;
@@ -12469,7 +12496,7 @@ function getUptimeFromPm2(runState) {
12469
12496
  var create4 = () => {
12470
12497
  return createCommand("status").summary("Show caw server status").param((p) => p.name("env-dir").type("string").flag("env-dir").default("~/.caw/")).run(async (ctx) => {
12471
12498
  const envDir = resolveEnvDir3(ctx.params["env-dir"]);
12472
- if (!fs11.existsSync(envDir) || !configExists(envDir)) {
12499
+ if (!fs12.existsSync(envDir) || !configExists(envDir)) {
12473
12500
  console.log("Server: not configured");
12474
12501
  console.log(` No environment found at ${envDir}`);
12475
12502
  process.exit(0);
@@ -12534,21 +12561,21 @@ var create4 = () => {
12534
12561
  var status_default = Object.freeze({ create: create4 });
12535
12562
 
12536
12563
  // src/commands/logs.js
12537
- import fs12 from "node:fs";
12538
- import path13 from "node:path";
12564
+ import fs13 from "node:fs";
12565
+ import path14 from "node:path";
12539
12566
  import os5 from "node:os";
12540
12567
  import { spawn as spawn2 } from "node:child_process";
12541
12568
  function resolveEnvDir4(rawEnvDir) {
12542
12569
  if (rawEnvDir.startsWith("~")) {
12543
- rawEnvDir = path13.join(os5.homedir(), rawEnvDir.slice(1));
12570
+ rawEnvDir = path14.join(os5.homedir(), rawEnvDir.slice(1));
12544
12571
  }
12545
- return path13.resolve(rawEnvDir);
12572
+ return path14.resolve(rawEnvDir);
12546
12573
  }
12547
12574
  var create5 = () => {
12548
12575
  return createCommand("logs").summary("Tail the caw server logs").param((p) => p.name("env-dir").type("string").flag("env-dir").default("~/.caw/")).run(async (ctx) => {
12549
12576
  const envDir = resolveEnvDir4(ctx.params["env-dir"]);
12550
- const logPath = path13.join(envDir, "server.log");
12551
- if (!fs12.existsSync(logPath)) {
12577
+ const logPath = path14.join(envDir, "server.log");
12578
+ if (!fs13.existsSync(logPath)) {
12552
12579
  console.log(`No log file found at ${logPath}`);
12553
12580
  process.exit(0);
12554
12581
  }
@@ -12570,16 +12597,16 @@ var logs_default = Object.freeze({ create: create5 });
12570
12597
 
12571
12598
  // src/commands/upgrade.js
12572
12599
  var import_semver2 = __toESM(require_semver2(), 1);
12573
- import fs13 from "node:fs";
12574
- import path14 from "node:path";
12600
+ import fs14 from "node:fs";
12601
+ import path15 from "node:path";
12575
12602
  import os6 from "node:os";
12576
12603
  import { execSync as execSync5 } from "node:child_process";
12577
12604
  var COMPATIBLE_SERVER_RANGE = "^1";
12578
12605
  function resolveEnvDir5(rawEnvDir) {
12579
12606
  if (rawEnvDir.startsWith("~")) {
12580
- rawEnvDir = path14.join(os6.homedir(), rawEnvDir.slice(1));
12607
+ rawEnvDir = path15.join(os6.homedir(), rawEnvDir.slice(1));
12581
12608
  }
12582
- return path14.resolve(rawEnvDir);
12609
+ return path15.resolve(rawEnvDir);
12583
12610
  }
12584
12611
  async function checkHealth3(port) {
12585
12612
  try {
@@ -12661,7 +12688,7 @@ var create6 = () => {
12661
12688
  let skipInstall = false;
12662
12689
  if (import_semver2.default.gte(installedVersion, latestServerVersion)) {
12663
12690
  let needsRestart = false;
12664
- if (fs13.existsSync(envDir) && configExists(envDir)) {
12691
+ if (fs14.existsSync(envDir) && configExists(envDir)) {
12665
12692
  const config = readConfigWithDefaults(envDir);
12666
12693
  const pm = createProcessManager(config, envDir);
12667
12694
  if (pm.isRunning().running) {
@@ -12708,7 +12735,7 @@ var create6 = () => {
12708
12735
  console.log("Rerun `caw upgrade` to complete the server upgrade.");
12709
12736
  process.exit(0);
12710
12737
  }
12711
- if (fs13.existsSync(envDir) && configExists(envDir)) {
12738
+ if (fs14.existsSync(envDir) && configExists(envDir)) {
12712
12739
  const envCheck = validateEnvFile(envDir);
12713
12740
  if (!envCheck.ok) {
12714
12741
  console.error(envCheck.message);
@@ -12716,7 +12743,7 @@ var create6 = () => {
12716
12743
  }
12717
12744
  }
12718
12745
  let serverWasStopped = false;
12719
- if (fs13.existsSync(envDir) && configExists(envDir)) {
12746
+ if (fs14.existsSync(envDir) && configExists(envDir)) {
12720
12747
  const config = readConfigWithDefaults(envDir);
12721
12748
  const pm = createProcessManager(config, envDir);
12722
12749
  const runState = pm.isRunning();
@@ -12767,7 +12794,7 @@ var create6 = () => {
12767
12794
  process.exit(1);
12768
12795
  }
12769
12796
  }
12770
- if (serverWasStopped || fs13.existsSync(envDir) && configExists(envDir)) {
12797
+ if (serverWasStopped || fs14.existsSync(envDir) && configExists(envDir)) {
12771
12798
  const config = readConfigWithDefaults(envDir);
12772
12799
  const pm = createProcessManager(config, envDir);
12773
12800
  const newServerInfo = resolve();
@@ -12793,15 +12820,15 @@ var create6 = () => {
12793
12820
  var upgrade_default = Object.freeze({ create: create6 });
12794
12821
 
12795
12822
  // src/commands/restart.js
12796
- import fs14 from "node:fs";
12797
- import path15 from "node:path";
12823
+ import fs15 from "node:fs";
12824
+ import path16 from "node:path";
12798
12825
  import os7 from "node:os";
12799
12826
  import { execSync as execSync6 } from "node:child_process";
12800
12827
  function resolveEnvDir6(rawEnvDir) {
12801
12828
  if (rawEnvDir.startsWith("~")) {
12802
- rawEnvDir = path15.join(os7.homedir(), rawEnvDir.slice(1));
12829
+ rawEnvDir = path16.join(os7.homedir(), rawEnvDir.slice(1));
12803
12830
  }
12804
- return path15.resolve(rawEnvDir);
12831
+ return path16.resolve(rawEnvDir);
12805
12832
  }
12806
12833
  function buildChangeSummary2(active, pending) {
12807
12834
  const changes = [];
@@ -12840,9 +12867,11 @@ var create7 = () => {
12840
12867
  }
12841
12868
  const envDir = resolveEnvDir6(ctx.params["env-dir"]);
12842
12869
  const force = ctx.params.force;
12843
- if (fs14.existsSync(envDir) && configExists(envDir)) {
12870
+ const hadConfig = fs15.existsSync(envDir) && configExists(envDir);
12871
+ if (hadConfig) {
12844
12872
  const config2 = readConfigWithDefaults(envDir);
12845
12873
  const pm3 = createProcessManager(config2, envDir);
12874
+ showAnalyticsNoticeOnce({ envDir });
12846
12875
  const result = await executeStop(pm3, config2, force, ctx.prompt, envDir);
12847
12876
  if (result.wasRunning && !result.stopped) {
12848
12877
  if (result.userDeclined) {
@@ -12895,6 +12924,9 @@ How would you like to proceed?`,
12895
12924
  console.log(`Server is already running on port ${config.port}.`);
12896
12925
  process.exit(0);
12897
12926
  }
12927
+ if (!hadConfig) {
12928
+ showAnalyticsNoticeOnce({ envDir });
12929
+ }
12898
12930
  await emitCawCmdStart({ config: readConfig(envDir) });
12899
12931
  let activeConfig = config;
12900
12932
  if (hasPendingConfig(envDir)) {
@@ -12940,7 +12972,7 @@ How would you like to proceed?`,
12940
12972
  const started = await pollHealth(activeConfig.port);
12941
12973
  if (!started) {
12942
12974
  console.error(`Server did not become healthy within 10 seconds.`);
12943
- console.error(`Check logs with: caw logs${envDir !== path15.join(os7.homedir(), ".caw") ? ` --env-dir ${envDir}` : ""}`);
12975
+ console.error(`Check logs with: caw logs${envDir !== path16.join(os7.homedir(), ".caw") ? ` --env-dir ${envDir}` : ""}`);
12944
12976
  process.exit(1);
12945
12977
  }
12946
12978
  console.log(`Server started successfully on http://localhost:${activeConfig.port}`);
@@ -12949,8 +12981,8 @@ How would you like to proceed?`,
12949
12981
  var restart_default = Object.freeze({ create: create7 });
12950
12982
 
12951
12983
  // src/commands/caddy.js
12952
- import fs15 from "node:fs";
12953
- import path16 from "node:path";
12984
+ import fs16 from "node:fs";
12985
+ import path17 from "node:path";
12954
12986
  import os8 from "node:os";
12955
12987
  import http from "node:http";
12956
12988
  import https from "node:https";
@@ -13286,7 +13318,7 @@ function launchctlLabelForPid(execFileSeam, uid, pid) {
13286
13318
  async function classifyPhase1({ options, deps }) {
13287
13319
  const {
13288
13320
  _execFile,
13289
- fs: fsDep = fs15,
13321
+ fs: fsDep = fs16,
13290
13322
  hasTty,
13291
13323
  uid,
13292
13324
  homeDir,
@@ -13297,10 +13329,10 @@ async function classifyPhase1({ options, deps }) {
13297
13329
  const sudoPath = paths.sudo ?? DEFAULT_SUDO_PATH;
13298
13330
  const usrLocalCaddy = paths.usrLocalCaddy ?? DEFAULT_USR_LOCAL_CADDY;
13299
13331
  const homebrewCaddy = paths.homebrewCaddy ?? DEFAULT_HOMEBREW_CADDY;
13300
- const caddyfilePath = paths.caddyfile ?? path16.join(homeDir, ".caw", "Caddyfile");
13301
- const plistPath = paths.plist ?? path16.join(homeDir, "Library", "LaunchAgents", `${options.label}.plist`);
13302
- const stdoutLogPath = paths.stdoutLog ?? path16.join(homeDir, ".caw", "caddy.out.log");
13303
- const stderrLogPath = paths.stderrLog ?? path16.join(homeDir, ".caw", "caddy.err.log");
13332
+ const caddyfilePath = paths.caddyfile ?? path17.join(homeDir, ".caw", "Caddyfile");
13333
+ const plistPath = paths.plist ?? path17.join(homeDir, "Library", "LaunchAgents", `${options.label}.plist`);
13334
+ const stdoutLogPath = paths.stdoutLog ?? path17.join(homeDir, ".caw", "caddy.out.log");
13335
+ const stderrLogPath = paths.stderrLog ?? path17.join(homeDir, ".caw", "caddy.err.log");
13304
13336
  let activeConfig;
13305
13337
  try {
13306
13338
  activeConfig = readConfigDep(options.envDir);
@@ -13309,7 +13341,7 @@ async function classifyPhase1({ options, deps }) {
13309
13341
  return {
13310
13342
  tag: "envdir-uninitialised",
13311
13343
  exitCode: 1,
13312
- message: `CAW is not configured on this machine ` + `(no config at ${path16.join(options.envDir, "config.json")}). ` + `Run \`caw start\` first, then \`brew install caddy\`, ` + `then re-run \`caw caddy setup\`.`
13344
+ message: `CAW is not configured on this machine ` + `(no config at ${path17.join(options.envDir, "config.json")}). ` + `Run \`caw start\` first, then \`brew install caddy\`, ` + `then re-run \`caw caddy setup\`.`
13313
13345
  };
13314
13346
  }
13315
13347
  return { tag: "envdir-malformed", exitCode: 1, message: e.message };
@@ -13591,7 +13623,7 @@ function sha256HexOfPem(pem) {
13591
13623
  return crypto4.createHash("sha256").update(der).digest("hex").toUpperCase();
13592
13624
  }
13593
13625
  function atomicWriteWithBackup({ fs: fsDep, path: filePath, content }) {
13594
- fsDep.mkdirSync(path16.dirname(filePath), { recursive: true });
13626
+ fsDep.mkdirSync(path17.dirname(filePath), { recursive: true });
13595
13627
  let priorContent = null;
13596
13628
  let hadPrior = false;
13597
13629
  try {
@@ -13746,7 +13778,7 @@ async function phase2Provision({ classification, options, deps, seams, generator
13746
13778
  priorCaPem: null,
13747
13779
  priorCaFingerprint: null,
13748
13780
  writes: { caddyfile: null, plist: null },
13749
- envDir: path16.dirname(classification.paths.stderrLog),
13781
+ envDir: path17.dirname(classification.paths.stderrLog),
13750
13782
  stderrLogPath: classification.paths.stderrLog,
13751
13783
  uid: deps.uid,
13752
13784
  domain: classification.activeConfig.domain,
@@ -14034,7 +14066,7 @@ async function performRollback({ rollbackCtx, trigger, error, deps, seams }) {
14034
14066
  }
14035
14067
  }
14036
14068
  const stamp = nowIso(deps).replace(/[:.]/g, "-");
14037
- const logPath = path16.join(rollbackCtx.envDir, `caw-caddy-setup-${stamp}.log`);
14069
+ const logPath = path17.join(rollbackCtx.envDir, `caw-caddy-setup-${stamp}.log`);
14038
14070
  const logBody = renderRollbackLog({ rollbackCtx, trigger, error, events, verifyResult });
14039
14071
  try {
14040
14072
  deps.fs.writeFileSync(logPath, logBody);
@@ -14090,9 +14122,9 @@ function resolveEnvDir7(rawEnvDir, homeDir) {
14090
14122
  if (typeof homeDir !== "string" || homeDir.length === 0) {
14091
14123
  throw new TypeError("resolveEnvDir: homeDir is required when rawEnvDir starts with ~");
14092
14124
  }
14093
- return path16.resolve(path16.join(homeDir, rawEnvDir.slice(1)));
14125
+ return path17.resolve(path17.join(homeDir, rawEnvDir.slice(1)));
14094
14126
  }
14095
- return path16.resolve(rawEnvDir);
14127
+ return path17.resolve(rawEnvDir);
14096
14128
  }
14097
14129
  function isPhase4Idempotent({ resolvedEnvDir, resolvedDomain, deps }) {
14098
14130
  const readCfg = deps.readConfig ?? readConfig;
@@ -14360,9 +14392,9 @@ function renderRecoveryLog({ resolvedEnvDir, resolvedDomain, phase4Result, serve
14360
14392
  }
14361
14393
  function writeRecoveryDiagnostic({ resolvedEnvDir, resolvedDomain, phase4Result, serverLogPath, deps }) {
14362
14394
  const stamp = nowIso(deps).replace(/[:.]/g, "-");
14363
- const logPath = path16.join(resolvedEnvDir, `caw-caddy-setup-${stamp}.log`);
14395
+ const logPath = path17.join(resolvedEnvDir, `caw-caddy-setup-${stamp}.log`);
14364
14396
  const body = renderRecoveryLog({ resolvedEnvDir, resolvedDomain, phase4Result, serverLogPath });
14365
- const fsDep = deps.fs ?? fs15;
14397
+ const fsDep = deps.fs ?? fs16;
14366
14398
  try {
14367
14399
  fsDep.writeFileSync(logPath, body);
14368
14400
  return { logPath, error: null };
@@ -14405,7 +14437,7 @@ function createSetupHandler(deps = {}) {
14405
14437
  });
14406
14438
  const phase1Deps = {
14407
14439
  _execFile,
14408
- fs: deps.fs ?? fs15,
14440
+ fs: deps.fs ?? fs16,
14409
14441
  hasTty: deps.hasTty ?? Boolean(process.stdin?.isTTY),
14410
14442
  uid: deps.uid ?? (process.getuid ? process.getuid() : 0),
14411
14443
  homeDir,
@@ -14434,7 +14466,7 @@ function createSetupHandler(deps = {}) {
14434
14466
  out(renderContinueSummary({ classification }));
14435
14467
  out("→ Phase 2: Provision");
14436
14468
  const phase2Deps = {
14437
- fs: deps.fs ?? fs15,
14469
+ fs: deps.fs ?? fs16,
14438
14470
  stderr: err,
14439
14471
  uid: phase1Deps.uid,
14440
14472
  adminPollAttempts: deps.adminPollAttempts,
@@ -14478,7 +14510,7 @@ function createSetupHandler(deps = {}) {
14478
14510
  const resolvedEnvDir = options.envDir;
14479
14511
  const resolvedDomain = classification.activeConfig.domain;
14480
14512
  const phase4Deps = {
14481
- fs: deps.fs ?? fs15,
14513
+ fs: deps.fs ?? fs16,
14482
14514
  now: deps.now,
14483
14515
  readConfig: deps.readConfigRaw ?? readConfig,
14484
14516
  writeConfig: deps.writeConfig ?? writeConfig,
@@ -14613,7 +14645,7 @@ async function runPhase4({ preflight, options, classification, seams, keychainPa
14613
14645
  return returnBase;
14614
14646
  case "recovered": {
14615
14647
  out(`← Phase 4: Cutover (recovered)`);
14616
- const serverLogPath = path16.join(resolvedEnvDir, "server.log");
14648
+ const serverLogPath = path17.join(resolvedEnvDir, "server.log");
14617
14649
  const diag = writeRecoveryDiagnostic({ resolvedEnvDir, resolvedDomain, phase4Result, serverLogPath, deps: phase4Deps });
14618
14650
  err(`Phase 4 (Cutover) failed on new config: ${phase4Result.originalError?.message ?? "(no message)"}. ` + `Reverse restart on prior config is /health-green — machine is on the PRIOR config. ` + `Recovery diagnostic: ${diag.logPath}${diag.error ? ` (write warning: ${diag.error.message})` : ""}`);
14619
14651
  exit(1);
@@ -14621,7 +14653,7 @@ async function runPhase4({ preflight, options, classification, seams, keychainPa
14621
14653
  }
14622
14654
  case "recovery-failed": {
14623
14655
  out(`← Phase 4: Cutover (recovery-failed)`);
14624
- const serverLogPath = path16.join(resolvedEnvDir, "server.log");
14656
+ const serverLogPath = path17.join(resolvedEnvDir, "server.log");
14625
14657
  const diag = writeRecoveryDiagnostic({ resolvedEnvDir, resolvedDomain, phase4Result, serverLogPath, deps: phase4Deps });
14626
14658
  err(`Phase 4 (Cutover) failed on new config: ${phase4Result.originalError?.message ?? "(no message)"}
14627
14659
  ` + `Reverse restart on prior config ALSO failed: ${phase4Result.recoveryError?.message ?? "(no message)"}
@@ -14649,8 +14681,9 @@ var caddy_default = caddyGroup;
14649
14681
  // src/main.js
14650
14682
  var [major] = process.versions.node.split(".").map(Number);
14651
14683
  if (major < 24) {
14652
- console.error(`caw requires Node.js 24 or later (found v${process.version}).`);
14684
+ console.error(`caw requires Node.js 24 or later (found ${process.version}).`);
14653
14685
  console.error("The caw-server package uses Node 24 features that are not available in older versions.");
14686
+ console.error(`See ${INSTALL_GUIDE_URL} for the full walkthrough.`);
14654
14687
  process.exit(1);
14655
14688
  }
14656
14689
  var globalCheck = checkGlobalInstall();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kelceyp/caw",
3
- "version": "1.0.42",
3
+ "version": "1.0.44",
4
4
  "type": "module",
5
5
  "description": "Unified Web/MCP server with React web app. MD document management, handlebars templating, agent orchestration (aka browser based reskinning of claude code, codex and cursor that allows any of these agents to use any other as subagents) and user stories",
6
6
  "keywords": [
@@ -14,7 +14,6 @@
14
14
  "developer-tools",
15
15
  "workflow",
16
16
  "knowledge-base",
17
- "local-first",
18
17
  "rag",
19
18
  "full-text-search",
20
19
  "markdown",