@kelceyp/caw 1.0.25 → 1.0.27

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.
package/README.md CHANGED
@@ -10,10 +10,6 @@ caw start
10
10
  ```
11
11
  Then open [http://localhost:2229](http://localhost:2229) in your browser.
12
12
 
13
- First time running CAW?
14
-
15
- Click "Get started with a sample project" on the welcome screen. CAW will provision a project with pre-configured knowledge base, templates and stories so you can build immediately.
16
-
17
13
  ![CAW overview](https://athenadesign.com.au/caw/stories-list.png)
18
14
 
19
15
  ## Unlock sustainable development
package/dist/caw.js CHANGED
@@ -10494,16 +10494,39 @@ var globalHandlerRegistry = new Map;
10494
10494
  import fs2 from "node:fs";
10495
10495
  import path from "node:path";
10496
10496
  import { execSync } from "node:child_process";
10497
- var NVM_INSTALLER_VERSION = "v0.40.3";
10497
+ var EXIT_PLATFORM = 100;
10498
+ var EXIT_ARCH = 101;
10499
+ var EXIT_NODE = 102;
10500
+ var EXIT_ROOT = 103;
10501
+ var EXIT_WRITABLE = 104;
10502
+ var INSTALL_GUIDE_URL = "https://athenadesign.com.au/caw/installation-guide";
10503
+ var GUIDE_TAIL = `See ${INSTALL_GUIDE_URL} for the full walkthrough.`;
10498
10504
  function buildPrefixWritableMessage(prefix) {
10499
- return `The npm global prefix directory is not writable: ${prefix}
10500
- ` + `This may prevent installing or updating caw-server.
10505
+ return `caw: writable preflight check failed.
10506
+ ` + `The npm global prefix is not writable.
10501
10507
 
10502
- ` + `Options:
10503
- ` + ` 1. Continue anyway (installation may fail; sudo installs work
10504
- ` + " day 1 but require `sudo npm install -g …` at every future\n" + " `caw upgrade`)\n" + ` 2. Use nvm to get a user-owned prefix (recommended)
10505
- ` + ` After reloading your shell you may see a
10506
- ` + " `zsh compinit: insecure directories` warning — run\n" + " `compaudit` (full guidance printed after you pick this option)\n" + " 3. Exit and fix permissions manually";
10508
+ ` + `sudo npm install -g @kelceyp/caw-server@latest
10509
+ ` + `(and, if the target server needs a newer launcher: sudo npm install -g @kelceyp/caw@latest)
10510
+
10511
+ ` + `${GUIDE_TAIL}
10512
+
10513
+ ` + `Observed prefix: ${prefix}
10514
+ ` + `Note: sudo may resolve a different Node than your login shell — compare \`node --version\` with \`sudo node --version\` before running.`;
10515
+ }
10516
+ function checkNodeVersion() {
10517
+ const major = parseInt(process.versions.node.split(".")[0], 10);
10518
+ if (major >= 24) {
10519
+ return { ok: true, message: null };
10520
+ }
10521
+ const message = `caw: node preflight check failed.
10522
+ ` + `caw requires Node.js 24 or later.
10523
+
10524
+ ` + `Install Node.js 24 or later (nvm is the recommended path to a user-owned Node).
10525
+
10526
+ ` + `${GUIDE_TAIL}
10527
+
10528
+ ` + `Observed Node: ${process.version}`;
10529
+ return { ok: false, message };
10507
10530
  }
10508
10531
  function checkGlobalInstall() {
10509
10532
  const scriptPath = process.argv[1];
@@ -10559,6 +10582,80 @@ function checkPrefixWritable() {
10559
10582
  };
10560
10583
  }
10561
10584
  }
10585
+ function checkPlatform() {
10586
+ if (process.platform === "darwin") {
10587
+ return { ok: true, message: null };
10588
+ }
10589
+ const message = `caw: platform preflight check failed.
10590
+ ` + `caw supports macOS only.
10591
+
10592
+ ` + `Install caw on a macOS (darwin) host.
10593
+
10594
+ ` + `${GUIDE_TAIL}
10595
+
10596
+ ` + `Observed platform: ${process.platform}`;
10597
+ return { ok: false, message };
10598
+ }
10599
+ function checkArch() {
10600
+ if (process.arch === "x64" || process.arch === "arm64") {
10601
+ return { ok: true, message: null };
10602
+ }
10603
+ const message = `caw: arch preflight check failed.
10604
+ ` + `caw supports x64 (Intel) and arm64 (Apple Silicon) only.
10605
+
10606
+ ` + `Install caw on a supported architecture.
10607
+
10608
+ ` + `${GUIDE_TAIL}
10609
+
10610
+ ` + `Observed arch: ${process.arch}`;
10611
+ return { ok: false, message };
10612
+ }
10613
+ function checkNotRoot() {
10614
+ const uid = process.getuid?.();
10615
+ if (uid !== 0) {
10616
+ return { ok: true, message: null };
10617
+ }
10618
+ const message = `caw: not-root preflight check failed.
10619
+ ` + `Refusing to run as root — this command must not be invoked under sudo.
10620
+
10621
+ ` + `Re-run the command without sudo.
10622
+
10623
+ ` + `${GUIDE_TAIL}`;
10624
+ return { ok: false, message };
10625
+ }
10626
+ function runInstallPreflight({ requireNotRoot }) {
10627
+ const platform = checkPlatform();
10628
+ if (!platform.ok) {
10629
+ return { ok: false, failedGate: "platform", message: platform.message, exitCode: EXIT_PLATFORM };
10630
+ }
10631
+ const arch = checkArch();
10632
+ if (!arch.ok) {
10633
+ return { ok: false, failedGate: "arch", message: arch.message, exitCode: EXIT_ARCH };
10634
+ }
10635
+ const node = checkNodeVersion();
10636
+ if (!node.ok) {
10637
+ return { ok: false, failedGate: "node", message: node.message, exitCode: EXIT_NODE };
10638
+ }
10639
+ if (requireNotRoot) {
10640
+ const notRoot = checkNotRoot();
10641
+ if (!notRoot.ok) {
10642
+ return { ok: false, failedGate: "root", message: notRoot.message, exitCode: EXIT_ROOT };
10643
+ }
10644
+ }
10645
+ const writable = checkPrefixWritable();
10646
+ if (!writable.ok) {
10647
+ return { ok: false, failedGate: "writable", message: writable.message, exitCode: EXIT_WRITABLE };
10648
+ }
10649
+ return { ok: true, failedGate: null, message: null };
10650
+ }
10651
+ function emitPreflightFailure(result, { warnOnly = false } = {}) {
10652
+ if (warnOnly) {
10653
+ console.log(result.message);
10654
+ return;
10655
+ }
10656
+ console.error(result.message);
10657
+ process.exit(result.exitCode);
10658
+ }
10562
10659
 
10563
10660
  // src/server-info.js
10564
10661
  import fs3 from "node:fs";
@@ -11071,6 +11168,11 @@ async function pollHealth(port, maxRetries = 10, intervalMs = 1000) {
11071
11168
  return false;
11072
11169
  }
11073
11170
  function attemptInstallServer() {
11171
+ const preflight = runInstallPreflight({ requireNotRoot: true });
11172
+ if (!preflight.ok) {
11173
+ emitPreflightFailure(preflight);
11174
+ return false;
11175
+ }
11074
11176
  try {
11075
11177
  execSync4("npm install -g @kelceyp/caw-server@^1 --loglevel=error", { stdio: "inherit" });
11076
11178
  return true;
@@ -11080,6 +11182,15 @@ function attemptInstallServer() {
11080
11182
  }
11081
11183
  var create2 = () => {
11082
11184
  return createCommand("start").summary("Start the caw server").param((p) => p.name("env-dir").type("string").flag("env-dir").default("~/.caw/")).run(async (ctx) => {
11185
+ const rootCheck = checkNotRoot();
11186
+ if (!rootCheck.ok) {
11187
+ emitPreflightFailure({
11188
+ ok: false,
11189
+ failedGate: "root",
11190
+ message: rootCheck.message,
11191
+ exitCode: EXIT_ROOT
11192
+ });
11193
+ }
11083
11194
  const envDir = resolveEnvDir(ctx.params["env-dir"]);
11084
11195
  const prefixCheck = checkPrefixWritable();
11085
11196
  if (!prefixCheck.ok) {
@@ -11089,30 +11200,13 @@ var create2 = () => {
11089
11200
 
11090
11201
  How would you like to proceed?`,
11091
11202
  choices: [
11092
- { label: "Continue anyway", value: "continue" },
11203
+ { label: "Continue anyway (installation will be re-checked; a fresh preflight will refuse if it still fails)", value: "continue" },
11093
11204
  { label: "Switch to nvm (recommended)", value: "nvm" },
11094
11205
  { label: "Exit", value: "exit" }
11095
11206
  ]
11096
11207
  });
11097
11208
  if (choice === "nvm") {
11098
- console.log(`
11099
- To install nvm and get a user-owned prefix:
11100
- curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_INSTALLER_VERSION}/install.sh | bash
11101
- nvm install 24
11102
- npm install -g @kelceyp/caw
11103
-
11104
- For a newer nvm release, check https://github.com/nvm-sh/nvm/releases
11105
- and substitute the tag into the curl URL above.
11106
-
11107
- After reloading your shell you may see a \`zsh compinit: insecure
11108
- directories\` warning — a pre-existing insecure entry on your zsh
11109
- fpath that compinit surfaces on the next shell (not caused by nvm).
11110
- To fix:
11111
- 1. Run \`compaudit\` to list offending paths.
11112
- 2. For each path, apply whichever is appropriate:
11113
- - chmod g-w,o-w <path> (if group/world writable)
11114
- - chown <you> <path> (if not owned by root or you)
11115
- Do not blanket-chmod without inspecting compaudit's output.`);
11209
+ console.log(`See ${INSTALL_GUIDE_URL} for the full walkthrough.`);
11116
11210
  process.exit(0);
11117
11211
  }
11118
11212
  if (choice === "exit") {
@@ -11559,21 +11653,20 @@ async function pollHealth2(port, maxRetries = 10, intervalMs = 1000) {
11559
11653
  }
11560
11654
  var create6 = () => {
11561
11655
  return createCommand("upgrade").summary("Upgrade caw-server to the latest version").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) => {
11656
+ const rootCheck = checkNotRoot();
11657
+ if (!rootCheck.ok) {
11658
+ emitPreflightFailure({
11659
+ ok: false,
11660
+ failedGate: "root",
11661
+ message: rootCheck.message,
11662
+ exitCode: EXIT_ROOT
11663
+ });
11664
+ }
11562
11665
  const envDir = resolveEnvDir5(ctx.params["env-dir"]);
11563
11666
  const force = ctx.params.force;
11564
- const prefixCheck = checkPrefixWritable();
11565
- if (!prefixCheck.ok) {
11566
- console.error("Error: npm global prefix is not writable.");
11567
- console.error(`
11568
- To upgrade with sudo, run:
11569
- sudo npm install -g @kelceyp/caw-server@latest
11570
- sudo npm install -g @kelceyp/caw@latest (only if the target server requires a newer launcher)
11571
-
11572
- Before running sudo, compare \`node --version\` with \`sudo node --version\`.
11573
- If they differ, sudo resolves a different Node — often an older, system-supplied one — and the packages install for a Node version you are not using.
11574
-
11575
- The recommended alternative is a user-owned prefix (e.g. via nvm), which removes the need for sudo on every future upgrade.`);
11576
- process.exit(1);
11667
+ const preflight = runInstallPreflight({ requireNotRoot: true });
11668
+ if (!preflight.ok) {
11669
+ emitPreflightFailure(preflight);
11577
11670
  }
11578
11671
  const serverInfo = resolve();
11579
11672
  if (!serverInfo) {
@@ -11759,6 +11852,11 @@ function buildChangeSummary2(active, pending) {
11759
11852
  return changes;
11760
11853
  }
11761
11854
  function attemptInstallServer2() {
11855
+ const preflight = runInstallPreflight({ requireNotRoot: true });
11856
+ if (!preflight.ok) {
11857
+ emitPreflightFailure(preflight);
11858
+ return false;
11859
+ }
11762
11860
  try {
11763
11861
  execSync6("npm install -g @kelceyp/caw-server@^1 --loglevel=error", { stdio: "inherit" });
11764
11862
  return true;
@@ -11768,6 +11866,15 @@ function attemptInstallServer2() {
11768
11866
  }
11769
11867
  var create7 = () => {
11770
11868
  return createCommand("restart").summary("Restart the caw server (stop then start)").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) => {
11869
+ const rootCheck = checkNotRoot();
11870
+ if (!rootCheck.ok) {
11871
+ emitPreflightFailure({
11872
+ ok: false,
11873
+ failedGate: "root",
11874
+ message: rootCheck.message,
11875
+ exitCode: EXIT_ROOT
11876
+ });
11877
+ }
11771
11878
  const envDir = resolveEnvDir6(ctx.params["env-dir"]);
11772
11879
  const force = ctx.params.force;
11773
11880
  if (fs12.existsSync(envDir) && configExists5(envDir)) {
@@ -11789,30 +11896,13 @@ var create7 = () => {
11789
11896
 
11790
11897
  How would you like to proceed?`,
11791
11898
  choices: [
11792
- { label: "Continue anyway", value: "continue" },
11899
+ { label: "Continue anyway (installation will be re-checked; a fresh preflight will refuse if it still fails)", value: "continue" },
11793
11900
  { label: "Switch to nvm (recommended)", value: "nvm" },
11794
11901
  { label: "Exit", value: "exit" }
11795
11902
  ]
11796
11903
  });
11797
11904
  if (choice === "nvm") {
11798
- console.log(`
11799
- To install nvm and get a user-owned prefix:
11800
- curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_INSTALLER_VERSION}/install.sh | bash
11801
- nvm install 24
11802
- npm install -g @kelceyp/caw
11803
-
11804
- For a newer nvm release, check https://github.com/nvm-sh/nvm/releases
11805
- and substitute the tag into the curl URL above.
11806
-
11807
- After reloading your shell you may see a \`zsh compinit: insecure
11808
- directories\` warning — a pre-existing insecure entry on your zsh
11809
- fpath that compinit surfaces on the next shell (not caused by nvm).
11810
- To fix:
11811
- 1. Run \`compaudit\` to list offending paths.
11812
- 2. For each path, apply whichever is appropriate:
11813
- - chmod g-w,o-w <path> (if group/world writable)
11814
- - chown <you> <path> (if not owned by root or you)
11815
- Do not blanket-chmod without inspecting compaudit's output.`);
11905
+ console.log(`See ${INSTALL_GUIDE_URL} for the full walkthrough.`);
11816
11906
  process.exit(0);
11817
11907
  }
11818
11908
  if (choice === "exit") {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kelceyp/caw",
3
- "version": "1.0.25",
3
+ "version": "1.0.27",
4
4
  "type": "module",
5
5
  "description": "Unified Web/MCP server with React web app. Provides MD document management, handlebars based templating (documents, prompts and saved searches), user stories including task management and search (rag, fts & metadata with query language). CAW works with any agent that supports MCP but has specific integrations for Claude Code, Codex and Cursor CLI that enable agent orchestration. For humans, think of this as a browser-based reskinning of these tools enabling all prompts and outputs to be captured. For agents, this means that any of these three agents can be used by any other as a \"sub-agent\". And this works recursively to a user configurable depth.",
6
6
  "keywords": [
@@ -1,8 +1,14 @@
1
1
  import { execSync } from 'node:child_process';
2
+ import { runInstallPreflight, emitPreflightFailure } from '../src/guards.js';
2
3
 
3
- try {
4
- execSync('npm install -g @kelceyp/caw-server@^1 --loglevel=error', { stdio: 'inherit' });
5
- } catch {
6
- console.warn('Could not install @kelceyp/caw-server automatically.');
7
- console.warn('Run "caw start" to retry installation.');
4
+ const preflight = runInstallPreflight({ requireNotRoot: false });
5
+ if (!preflight.ok) {
6
+ emitPreflightFailure(preflight, { warnOnly: true });
7
+ } else {
8
+ try {
9
+ execSync('npm install -g @kelceyp/caw-server@^1 --loglevel=error', { stdio: 'inherit' });
10
+ } catch {
11
+ console.warn('Could not install @kelceyp/caw-server automatically.');
12
+ console.warn('Run "caw start" to retry installation.');
13
+ }
8
14
  }