@pixelfactoryio/theway 0.4.0 → 0.5.1

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
@@ -9,13 +9,13 @@ theway writes a spec and a numbered task list before any code, then implements t
9
9
  ## Install
10
10
 
11
11
  ```bash
12
- npx --yes github:pixelfactoryio/theway install
12
+ npx --yes @pixelfactoryio/theway@latest install
13
13
  ```
14
14
 
15
15
  Pin to a release:
16
16
 
17
17
  ```bash
18
- npx --yes github:pixelfactoryio/theway#vX.Y.Z install
18
+ npx --yes @pixelfactoryio/theway@X.Y.Z install
19
19
  ```
20
20
 
21
21
  ## Documentation
package/dist/theway.js CHANGED
@@ -2094,6 +2094,72 @@ function isFile(path2) {
2094
2094
 
2095
2095
  // src/core/list.ts
2096
2096
  import { readdirSync, readFileSync as readFileSync2 } from "node:fs";
2097
+
2098
+ // src/core/path.ts
2099
+ import { join as join2, resolve as resolve2 } from "node:path";
2100
+ var CHANGE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
2101
+ var PROJECT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
2102
+ function changeIdReason(v) {
2103
+ if (v === "")
2104
+ return "must not be empty";
2105
+ if (v.length > 200)
2106
+ return "must be at most 200 characters";
2107
+ if (!CHANGE_ID.test(v))
2108
+ return "must be lowercase letters and digits in words separated by single hyphens";
2109
+ return "";
2110
+ }
2111
+ function projectReason(v) {
2112
+ if (v === "")
2113
+ return "must not be empty";
2114
+ if (v.length > 200)
2115
+ return "must be at most 200 characters";
2116
+ if (!PROJECT.test(v))
2117
+ return 'must be letters, digits, ".", "_" or "-", not starting with "." or "-"';
2118
+ return "";
2119
+ }
2120
+ function invalidSegments(segments) {
2121
+ for (const [label, value] of segments) {
2122
+ if (value === undefined)
2123
+ continue;
2124
+ const reason = label === "project" ? projectReason(value) : changeIdReason(value);
2125
+ if (reason !== "") {
2126
+ const shown = value.replaceAll(`
2127
+ `, "\\n").replaceAll("\r", "\\r");
2128
+ process.stderr.write(`theway: invalid ${label} '${shown}': ${reason}
2129
+ `);
2130
+ return true;
2131
+ }
2132
+ }
2133
+ return false;
2134
+ }
2135
+ function cmdPath(project, changeId, verbose) {
2136
+ if (invalidSegments([
2137
+ ["project", project],
2138
+ ["change id", changeId]
2139
+ ]))
2140
+ return 1;
2141
+ const { home, source } = resolveHome();
2142
+ if (verbose)
2143
+ process.stderr.write(`theway: home ${home} (from ${source})
2144
+ `);
2145
+ if (source === "env") {
2146
+ const pointer = readPointer();
2147
+ if (pointer !== "" && resolve2(pointer) !== home) {
2148
+ process.stderr.write(`theway: warning: THEWAY_HOME is ${home} (from env) but ${pointerPath()} holds ${resolve2(pointer)} (from pointer); using ${home}
2149
+ `);
2150
+ }
2151
+ }
2152
+ let out = home;
2153
+ if (project !== undefined)
2154
+ out = join2(home, project);
2155
+ if (project !== undefined && changeId !== undefined)
2156
+ out = join2(home, project, "changes", changeId);
2157
+ process.stdout.write(`${out}
2158
+ `);
2159
+ return 0;
2160
+ }
2161
+
2162
+ // src/core/list.ts
2097
2163
  var CHECKED = /^\s*-\s*\[x\]\s+[0-9]+[a-z]?\./;
2098
2164
  var UNCHECKED = /^\s*-\s*\[ \]\s+[0-9]+[a-z]?\./;
2099
2165
  function visibleNames(dir) {
@@ -2132,6 +2198,8 @@ function taskCounts(dir) {
2132
2198
  return [checked, total];
2133
2199
  }
2134
2200
  function cmdList(project) {
2201
+ if (invalidSegments([["project", project]]))
2202
+ return 1;
2135
2203
  const home = thewayHome();
2136
2204
  const base = `${home}/${project}/changes`;
2137
2205
  let text = `theway changes — ${project}
@@ -2182,6 +2250,11 @@ function uncheckedLines(path2) {
2182
2250
  `).flatMap((line, i) => UNCHECKED.test(line) ? [`${i + 1}:${line}`] : []);
2183
2251
  }
2184
2252
  function cmdArchive(project, changeId, force) {
2253
+ if (invalidSegments([
2254
+ ["project", project],
2255
+ ["change id", changeId]
2256
+ ]))
2257
+ return 1;
2185
2258
  const home = thewayHome();
2186
2259
  const src = `${home}/${project}/changes/${changeId}`;
2187
2260
  const dst = `${home}/${project}/changes/archive/${localDate()}-${changeId}`;
@@ -2226,55 +2299,6 @@ ${list}`);
2226
2299
  return 0;
2227
2300
  }
2228
2301
 
2229
- // src/core/path.ts
2230
- import { join as join2, resolve as resolve2 } from "node:path";
2231
- function segmentReason(name) {
2232
- if (name === "")
2233
- return "must not be empty";
2234
- if (name.includes("/"))
2235
- return "must not contain /";
2236
- if (name === "." || name === "..")
2237
- return `must not be ${name}`;
2238
- return "";
2239
- }
2240
- function cmdPath(project, changeId, verbose) {
2241
- const segments = [
2242
- ["project", project],
2243
- ["change id", changeId]
2244
- ];
2245
- for (const [label, value] of segments) {
2246
- if (value === undefined)
2247
- continue;
2248
- const reason = segmentReason(value);
2249
- if (reason !== "") {
2250
- const shown = value.replaceAll(`
2251
- `, "\\n").replaceAll("\r", "\\r");
2252
- process.stderr.write(`theway: invalid ${label} '${shown}': ${reason}
2253
- `);
2254
- return 1;
2255
- }
2256
- }
2257
- const { home, source } = resolveHome();
2258
- if (verbose)
2259
- process.stderr.write(`theway: home ${home} (from ${source})
2260
- `);
2261
- if (source === "env") {
2262
- const pointer = readPointer();
2263
- if (pointer !== "" && resolve2(pointer) !== home) {
2264
- process.stderr.write(`theway: warning: THEWAY_HOME is ${home} (from env) but ${pointerPath()} holds ${resolve2(pointer)} (from pointer); using ${home}
2265
- `);
2266
- }
2267
- }
2268
- let out = home;
2269
- if (project !== undefined)
2270
- out = join2(home, project);
2271
- if (project !== undefined && changeId !== undefined)
2272
- out = join2(home, project, "changes", changeId);
2273
- process.stdout.write(`${out}
2274
- `);
2275
- return 0;
2276
- }
2277
-
2278
2302
  // src/core/validate-id.ts
2279
2303
  var VERB = /^(add|update|refactor|remove)-/;
2280
2304
  var KEBAB = /^(add|update|refactor|remove)-[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -2344,14 +2368,16 @@ import {
2344
2368
  lstatSync,
2345
2369
  mkdirSync as mkdirSync3,
2346
2370
  readFileSync as readFileSync4,
2371
+ readlinkSync,
2347
2372
  realpathSync,
2348
2373
  renameSync as renameSync2,
2349
2374
  rmdirSync,
2350
2375
  rmSync,
2376
+ statSync as statSync2,
2351
2377
  writeFileSync
2352
2378
  } from "node:fs";
2353
2379
  import { homedir as homedir2 } from "node:os";
2354
- import { delimiter, dirname, join as join3, resolve as resolve3 } from "node:path";
2380
+ import { delimiter, dirname, join as join3, resolve as resolve3, sep } from "node:path";
2355
2381
  import { fileURLToPath } from "node:url";
2356
2382
 
2357
2383
  // src/core/init.ts
@@ -2438,11 +2464,48 @@ function readSettings(path2) {
2438
2464
  }
2439
2465
  return data;
2440
2466
  }
2441
- function writeSettings(path2, settings) {
2442
- const tmp = `${path2}.tmp-${process.pid}`;
2443
- writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}
2444
- `);
2445
- renameSync2(tmp, path2);
2467
+ function settingsTarget(path2) {
2468
+ let target = path2;
2469
+ const seen = new Set;
2470
+ for (;; ) {
2471
+ let link;
2472
+ try {
2473
+ link = lstatSync(target).isSymbolicLink();
2474
+ } catch {
2475
+ break;
2476
+ }
2477
+ if (!link)
2478
+ break;
2479
+ if (seen.has(target) || seen.size >= 40)
2480
+ return { error: "it is a symlink loop" };
2481
+ seen.add(target);
2482
+ target = resolve3(dirname(target), readlinkSync(target));
2483
+ }
2484
+ let dir = dirname(target);
2485
+ while (!existsSync3(dir) && dirname(dir) !== dir)
2486
+ dir = dirname(dir);
2487
+ try {
2488
+ accessSync(dir, constants.W_OK);
2489
+ } catch {
2490
+ return { error: `${dir} is not writable` };
2491
+ }
2492
+ return { target };
2493
+ }
2494
+ function unwritableSettings(path2, reason) {
2495
+ return fail(`theway: cannot write ${path2}: ${reason}; nothing was changed`);
2496
+ }
2497
+ function writeSettings(target, settings) {
2498
+ mkdirSync3(dirname(target), { recursive: true });
2499
+ const mode = existsSync3(target) ? statSync2(target).mode & 511 : 384;
2500
+ const tmp = `${target}.tmp-${process.pid}`;
2501
+ try {
2502
+ writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}
2503
+ `, { mode });
2504
+ chmodSync(tmp, mode);
2505
+ renameSync2(tmp, target);
2506
+ } finally {
2507
+ rmSync(tmp, { force: true });
2508
+ }
2446
2509
  }
2447
2510
  function invalidSettings(path2) {
2448
2511
  return fail(`theway: ${path2} is not valid settings JSON; nothing was changed`);
@@ -2471,11 +2534,25 @@ function removeIfEmpty(dir) {
2471
2534
  rmdirSync(dir);
2472
2535
  } catch {}
2473
2536
  }
2537
+ function legacyText(path2, match) {
2538
+ try {
2539
+ return lstatSync(path2).isFile() && match(readFileSync4(path2, "utf-8"));
2540
+ } catch {
2541
+ return false;
2542
+ }
2543
+ }
2474
2544
  function removeLegacyBin(home) {
2475
2545
  for (const h of new Set([defaultHome(), resolve3(home)])) {
2476
2546
  const bin = join3(h, "bin");
2477
- for (const f of ["theway", "theway.js"])
2478
- rmSync(join3(bin, f), { force: true });
2547
+ if (legacyText(join3(bin, "theway"), (t) => t.startsWith(`#!/bin/sh
2548
+ exec node `) && t.endsWith(`theway.js' "$@"
2549
+ `))) {
2550
+ rmSync(join3(bin, "theway"), { force: true });
2551
+ }
2552
+ if (legacyText(join3(bin, "theway.js"), (t) => t.startsWith(`#!/usr/bin/env node
2553
+ `))) {
2554
+ rmSync(join3(bin, "theway.js"), { force: true });
2555
+ }
2479
2556
  removeIfEmpty(bin);
2480
2557
  }
2481
2558
  }
@@ -2527,6 +2604,17 @@ function realpathOr(path2) {
2527
2604
  return resolve3(path2);
2528
2605
  }
2529
2606
  }
2607
+ function unsafeHomeReason(tHome, custom) {
2608
+ const home = resolve3(tHome);
2609
+ const real = realpathOr(home);
2610
+ const user = realpathOr(homedir2());
2611
+ if (real === user || user.startsWith(real + sep) || real === "/") {
2612
+ return "it is your home folder or one of its parents";
2613
+ }
2614
+ if (custom && /[*?[\]{}\n\r]/.test(home))
2615
+ return "it contains a glob character or a line break";
2616
+ return "";
2617
+ }
2530
2618
  function copiesOnPath() {
2531
2619
  const running = realpathOr(self);
2532
2620
  const seen = new Set;
@@ -2564,7 +2652,7 @@ function checkPath(dir, binary) {
2564
2652
  }
2565
2653
  function install() {
2566
2654
  if (!existsSync3(join3(plugin, ".claude-plugin"))) {
2567
- return fail("theway: run `npx --yes github:pixelfactoryio/theway install` to install or update theway");
2655
+ return fail("theway: run `npx --yes @pixelfactoryio/theway@latest install` to install or update theway");
2568
2656
  }
2569
2657
  const cHome = claudeHome();
2570
2658
  const tHome = resolveHome().home;
@@ -2572,7 +2660,14 @@ function install() {
2572
2660
  const custom = tHome !== resolve3(defaultHome());
2573
2661
  const dir = installDir();
2574
2662
  const settingsPath = join3(cHome, "settings.json");
2575
- const settings = readSettings(settingsPath);
2663
+ const unsafe = unsafeHomeReason(tHome, custom);
2664
+ if (unsafe !== "") {
2665
+ return fail(`theway: refusing data home ${resolve3(tHome)}: ${unsafe}; set THEWAY_HOME to a dedicated folder`);
2666
+ }
2667
+ const resolved = settingsTarget(settingsPath);
2668
+ if ("error" in resolved)
2669
+ return unwritableSettings(settingsPath, resolved.error);
2670
+ const settings = readSettings(resolved.target);
2576
2671
  if (settings === null)
2577
2672
  return invalidSettings(settingsPath);
2578
2673
  const target = join3(dir, "theway");
@@ -2604,7 +2699,7 @@ function install() {
2604
2699
  if (missing.length > 0 || kept.length !== allow.length) {
2605
2700
  settings.permissions = { ...perms, allow: [...kept, ...missing] };
2606
2701
  mkdirSync3(cHome, { recursive: true });
2607
- writeSettings(settingsPath, settings);
2702
+ writeSettings(resolved.target, settings);
2608
2703
  }
2609
2704
  checkPath(dir, binary);
2610
2705
  const version = JSON.parse(readFileSync4(join3(pkgRoot, "package.json"), "utf-8")).version;
@@ -2617,6 +2712,13 @@ function uninstall() {
2617
2712
  const tHome = resolveHome().home;
2618
2713
  const homes = [...new Set([tHome, recordedHome(), defaultHome()])];
2619
2714
  const settingsPath = join3(cHome, "settings.json");
2715
+ let settingsFile = settingsPath;
2716
+ if (occupied(settingsPath)) {
2717
+ const resolved = settingsTarget(settingsPath);
2718
+ if ("error" in resolved)
2719
+ return unwritableSettings(settingsPath, resolved.error);
2720
+ settingsFile = resolved.target;
2721
+ }
2620
2722
  rmSync(join3(cHome, "skills", "theway"), { recursive: true, force: true });
2621
2723
  const binary = join3(installDir(), "theway");
2622
2724
  const removed = isThewayBinary(binary);
@@ -2625,7 +2727,7 @@ function uninstall() {
2625
2727
  rmSync(pointerPath(), { force: true });
2626
2728
  removeIfEmpty(dirname(pointerPath()));
2627
2729
  if (existsSync3(settingsPath)) {
2628
- const settings = readSettings(settingsPath);
2730
+ const settings = readSettings(settingsFile);
2629
2731
  if (settings === null)
2630
2732
  return invalidSettings(settingsPath);
2631
2733
  const allow = settings.permissions?.allow;
@@ -2634,7 +2736,7 @@ function uninstall() {
2634
2736
  const kept = allow.filter((r) => !(typeof r === "string" && drop.includes(r)));
2635
2737
  if (kept.length !== allow.length) {
2636
2738
  settings.permissions = { ...settings.permissions, allow: kept };
2637
- writeSettings(settingsPath, settings);
2739
+ writeSettings(settingsFile, settings);
2638
2740
  }
2639
2741
  }
2640
2742
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pixelfactoryio/theway",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
4
4
  "description": "A spec-first workflow for Claude Code",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "theway",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
4
4
  "description": "theway writes a spec and a numbered task list before any code, then implements the tasks in your session or through agents that open a reviewed, CI-green pull request.",
5
5
  "author": {
6
6
  "name": "Amine",
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  description: Install or update theway from a Claude Code session
3
3
  author: Amine
4
- allowed-tools: Bash(npx --yes github:pixelfactoryio/theway install)
4
+ allowed-tools: Bash(npx --yes @pixelfactoryio/theway@latest install)
5
5
  ---
6
6
 
7
7
  # TheWay: Setup
@@ -13,7 +13,7 @@ One-time setup: installs the `theway` CLI on your `PATH` and initializes the the
13
13
  ### Step 1: Run the Installer
14
14
 
15
15
  ```bash
16
- npx --yes github:pixelfactoryio/theway install
16
+ npx --yes @pixelfactoryio/theway@latest install
17
17
  ```
18
18
 
19
19
  ### Step 2: Check the Result
@@ -11,7 +11,7 @@ Use TheWay slash commands for structured workflows:
11
11
  - `/theway:archive` - Archive completed changes
12
12
  - `/theway:list` - List active and archived changes
13
13
 
14
- Install with `npx --yes github:pixelfactoryio/theway install` (or `/theway:setup` from a session where theway is loaded).
14
+ Install with `npx --yes @pixelfactoryio/theway@latest install` (or `/theway:setup` from a session where theway is loaded).
15
15
 
16
16
  `theway` subcommands (on `PATH`): `list`, `archive`, `path [<project> [<change-id>]] [--verbose]` (prints the theway home, a project folder or a change folder; `--verbose` names where the home came from) and `validate-id <id> [--series]` (change ID format check from `/theway:engineering` Step 2: exit 0 when valid, exit 1 with one reason on stderr).
17
17
  <!-- THEWAY:END -->