axstack 0.34.0 → 0.34.2

package/README.md

@@ -147,6 +147,24 @@ Eligible own PRs use guarded automatic merge; see [merge boundaries, exclusions,
 See [PR scope and sizing](skills/axstack/references/pr-shape.md) for candidate
 shape and [Releases](https://github.com/axatbhardwaj/axstack/releases) for release history.
 
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run lint
+bun run typecheck
+git config core.hooksPath .husky
+```
+
+The hook is opt-in per clone via `git config core.hooksPath .husky` and requires
+`bun install`. Without dev tools it prints a setup hint and skips the checks.
+The hook runs lint and typecheck only. Biome formatting is optional for editors
+or manual use; commits do not enforce formatting. TypeScript checks JavaScript
+in `src/` and `bin/` without emitting files. All tooling is development-only and
+is excluded from packed assets by `package.json.files`.
+Regenerate `bun.lock` with the minimum Bun version in `package.json.engines`
+(currently 1.3.14); newer Bun versions can write an incompatible lockfile format.
+
 ## License
 
 [MIT](LICENSE) © 2026 Axat Bhardwaj.

package/bin/axstack.js

@@ -26,7 +26,7 @@ function homeDir() {
   // Tilde expansion needs a known absolute home; with HOME missing, empty,
   // or relative the destination is unknown, so refuse even with --yes.
   const home = Bun.env.HOME;
-  if (!home || !home.startsWith('/')) {
+  if (!home?.startsWith('/')) {
     throw new Error('HOME is missing, empty, or not absolute; pass explicit paths instead of ~');
   }
   return home;
@@ -298,6 +298,13 @@ async function main() {
       const legacyCodexManifest = legacyCodexDir
         ? await readLegacySkillsManifest(legacyCodexDir)
         : null;
+      /**
+       * @type {Awaited<ReturnType<typeof installBundle>> & {
+       *   legacyCodex?: {removed: string[], preserved: string[], missing: string[], skipped?: boolean,
+       *     held?: boolean, failed?: boolean, failure?: boolean, reason?: string},
+       *   addedRoleIds?: string[], removedRoleIds?: string[], changedRoleModels?: string[], notes?: string[]
+       * }}
+       */
       const summary = await installBundle({
         bundleDir: flags.bundle ? resolve(flags.bundle) : PACKAGE_ROOT,
         skillsDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.34.0",
+  "version": "0.34.2",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks T3 Code capabilities.",
   "keywords": [
     "claude-code",
@@ -32,8 +32,15 @@
     "docs/*.md"
   ],
   "scripts": {
+    "lint": "biome lint . --error-on-warnings",
+    "typecheck": "bun node_modules/typescript/bin/tsc --noEmit --project jsconfig.json",
     "test": "bun test",
     "test:all": "bun test"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/bun": "1.4.2",
+    "typescript": "7.0.2"
+  }
 }

package/skills/axstack/scripts/pr-digest.js

@@ -54,7 +54,7 @@ function fetchCurrent(args) {
 }
 
 function nodes(connection, field) {
-  if (!connection || connection.pageInfo?.hasNextPage !== false || !Array.isArray(connection.nodes)) {
+  if (connection?.pageInfo?.hasNextPage !== false || !Array.isArray(connection.nodes)) {
     throw new Error(`incomplete ${field} connection`);
   }
   return connection.nodes;

package/skills/axstack-relay/SKILL.md

@@ -155,20 +155,36 @@ reissuing only if a decision is still needed.
 Each card must carry exactly one decision.
 The card ID must be `<run id>/<n>`, never reused in the driver thread.
 The only sender of reply-dependent cards must be the run's driver.
+
+Decision cards and explain answers must use short paragraphs with blank lines
+between thoughts for reading on a phone.
+Decision cards and explain answers must use ordinary words and briefly define
+necessary technical terms.
+Each decision card must explain what is happening and why the choice matters.
+Each numbered option must state the concrete action, scope, expected outcome
+and material trade-off.
+Defer and Cancel must describe the withheld action and what remains unresolved.
+Any recommendation must include a brief evidence-supported reason.
+A recommendation must leave the choice to the user.
+
 Use plain ASCII for the card layout below, as one message:
 
 ```text
 <project> - <decision title>
 Card <run id>/<n>[, confirms card <run id>/<m>]
+
 Context: <what we were doing, one line>
 Decision: <the question>
+
+1 <action> - <scope; outcome; trade-off>
+2 <action> - <scope; outcome; trade-off>
+3 Defer - <deferred action and scope; outcome; trade-off> (optional)
+
 Driver environment: <value | not supplied>
 Execution machine: <value | not supplied>
 Affected targets: <values | not supplied>
 Revision: <repo#PR @ full SHA | spec rev N sha256 | none>
-1 <action> - <scope>
-2 <action> - <scope>
-3 Defer (optional)
+
 Reply 1, 2, 3 or explain. Open T3: <link | not available>
 T3 reply: <env label> thread <driver threadId>
 ```
@@ -250,6 +266,13 @@ Run these four checks in order, stopping at the first failure:
    Free text is user input, not a numbered option, and gets the same authority
    revalidation and confirmation checks before it can authorize an action.
 
+Explain answers must directly address the reader's confusion.
+Explain answers must expand meaningful context and each option's consequences.
+Explain answers must give a justified recommendation when evidence supports it.
+Explain answers must state material risks and unknown facts plainly.
+Never merely restate IDs or SHAs in an explain answer.
+The same one-message size and final reply tag rules apply to explain answers.
+
 ## Confirm, acknowledge and act
 
 Any forwarded reply, including free text and `(confirm)` options, authorizing
@@ -257,6 +280,13 @@ a destructive, production or fleet-wide action must first get a confirmation car
 A confirmation card must have its own ID, name the card it confirms
 (`confirms card`), bind the exact action, execution machine, affected targets
 and revision, and offer `1 Confirm` and `2 Cancel`.
+Use the same detail fields for confirmation option rows:
+
+```text
+1 Confirm - <bound action and scope; outcome; trade-off>
+2 Cancel - <withheld action and scope; outcome; trade-off>
+```
+
 Sending a confirmation must record the original card decided, pending
 confirmation with no authority.
 The driver must allow only a verified `1` on the open confirmation to authorize

package/src/archify.js

@@ -19,6 +19,7 @@ export function archifyGit(path, ...args) {
 
 function verifySha(record, actual) {
   if (actual === record.sha) return;
+  /** @type {Error & {code?: string}} */
   const error = new Error(`archify SHA mismatch: expected ${record.sha}, got ${actual}`);
   error.code = 'ARCHIFY_SHA_MISMATCH';
   throw error;
@@ -31,7 +32,8 @@ async function ownersSnapshot(path) {
   });
   if (st && (!st.isFile() || st.isSymbolicLink())) throw new Error(`unsafe archify owners file: ${path}`);
   const bytes = st ? await readFile(path) : null;
-  const owners = bytes ? JSON.parse(bytes) : [];
+  // JSON.parse coerces its argument to a string; preserve the existing Buffer coercion.
+  const owners = bytes ? /** @type {(text: {toString(): string}) => unknown} */ (JSON.parse)(bytes) : [];
   if (!Array.isArray(owners) || owners.some((owner) => typeof owner !== 'string' || !owner.startsWith('/'))) {
     throw new Error(`invalid archify owners file: ${path}`);
   }

package/src/claude-settings.js

@@ -184,7 +184,7 @@ export async function planUninstallClaudeSettings({ claude, skillsRoot, boundPat
   }
 
   const owned = sidecar.keys[CLAUDE_SETTING_PATH];
-  if (!owned || !owned.owners.includes(skillsRoot)) {
+  if (!owned?.owners.includes(skillsRoot)) {
     return {
       report: { status: 'skipped', reason: 'this skills directory does not own the Claude setting' },
       writes: [],

package/src/installer.js

@@ -179,7 +179,7 @@ function homeDir() {
   // aliased HOME) compare equal to canonicalized targets; an unresolvable
   // HOME also yields null and fails closed rather than bypassing the guard.
   const home = Bun.env.HOME;
-  if (!home || !home.startsWith('/')) return null;
+  if (!home?.startsWith('/')) return null;
   try {
     return realpathSync(home);
   } catch {
@@ -238,7 +238,7 @@ export async function validateBundle(bundleDir, selectedPreset = null) {
   if (skillsStat.isSymbolicLink() || !skillsStat.isDirectory()) {
     throw new Error('bundle skills/ must be a real directory, not a symlink');
   }
-  let entries = await readdir(skillsRoot, { withFileTypes: true });
+  const entries = await readdir(skillsRoot, { withFileTypes: true });
   // Symlinked (or non-directory) top-level skill entries must be rejected,
   // not silently skipped: Dirent.isDirectory() is false for symlinks.
   for (const entry of entries) {
@@ -380,6 +380,11 @@ async function walkSkills(dir, skillsRoot, out) {
 // never followed or truncated. After the rename, existing permissions are
 // preserved; new files take an explicit `mode` (e.g. 0600 for configs) or
 // the umask default. Guards pre-existing entries, not active races.
+/**
+ * @param {string} dest
+ * @param {string | Uint8Array} bytes
+ * @param {{mode?: number}} [options]
+ */
 export async function writeAtomic(dest, bytes, { mode } = {}) {
   await mkdir(dirname(dest), { recursive: true });
   let existingMode = null;
@@ -408,6 +413,7 @@ export async function writeAtomic(dest, bytes, { mode } = {}) {
   }
 }
 
+/** @param {Pick<InstallerOptions, 'skillsDir' | 'instructionsPath'>} [options] */
 export async function checkInstructionBinding({ skillsDir, instructionsPath } = {}) {
   if (!skillsDir) throw new Error('instruction check requires --skills-dir <dir> or --harness <name>');
   if (!instructionsPath) throw new Error('instruction check requires --instructions <file> or a supported harness');
@@ -467,6 +473,21 @@ async function assertFileSnapshot(dest, expected) {
   }
 }
 
+/**
+ * @typedef {{available: boolean, settingsPath?: string, skip?: boolean, reason?: string}} ClaudeOption
+ * @typedef {Object} InstallerOptions
+ * @property {string} [skillsDir]
+ * @property {string} [instructionsPath]
+ * @property {boolean} [force]
+ * @property {boolean} [yes]
+ * @property {ClaudeOption} [claude]
+ * @property {(message: string) => void} [log]
+ */
+
+/**
+ * @param {InstallerOptions & {bundleDir?: string, preset?: string, toolsDir?: string,
+ *   inheritedInstructions?: {path: string, hash: string}}} [options]
+ */
 export async function installBundle({
   bundleDir,
   skillsDir,
@@ -857,6 +878,7 @@ export async function installBundle({
   }
 }
 
+/** @param {InstallerOptions} [options] */
 export async function uninstallBundle({
   skillsDir,
   instructionsPath = null,
@@ -1110,6 +1132,10 @@ export async function uninstallBundle({
 // is present and byte-for-byte verified. This deliberately handles skill
 // payloads only: instruction files, Claude settings, and historical profile
 // ownership may belong to another harness and remain bound to the old manifest.
+/**
+ * @param {{canonicalSkillsDir?: string, legacySkillsDir?: string, yes?: boolean,
+ *   acceptedInstructionTransfer?: {path: string, legacyHash: string, canonicalHash: string}}} [options]
+ */
 export async function retireLegacySkills({
   canonicalSkillsDir,
   legacySkillsDir,

package/src/posixpath.js

@@ -65,7 +65,8 @@ export function resolveFrom(cwd, ...paths) {
 }
 
 export function resolve(...paths) {
-  return resolveFrom(Bun.cwd, ...paths);
+  // Bun.cwd is a runtime string missing from the current Bun declarations.
+  return resolveFrom(/** @type {typeof Bun & {cwd: string}} */ (Bun).cwd, ...paths);
 }
 
 export function relative(from, to) {