devsync-ai 0.0.1 → 0.1.0-rc.2

package/README.md

@@ -3,3 +3,76 @@
 This package name is reserved for DevSync (https://devsync.ai), a neutral command surface for AI coding agents.
 
 It is under development. This 0.0.1 release is a placeholder and contains no functionality.
+
+## Distribution
+
+How DevSync ships on npm (decision D12). Nothing here is published by agents; the user publishes.
+
+### Packages
+
+| Package | Holds |
+| --- | --- |
+| `devsync-ai` | The `devsync` command: a small JS launcher (`bin/devsync.js`) and nothing else. Lists the four platform packages below as `optionalDependencies`, pinned to its own version. |
+| `devsync-ai-linux-x64` | `bin/devsync` and `bin/devsync-hook` for Linux on x86-64 (`os: ["linux"]`, `cpu: ["x64"]`) |
+| `devsync-ai-linux-arm64` | the same for Linux on ARM64 (`os: ["linux"]`, `cpu: ["arm64"]`) |
+| `devsync-ai-darwin-x64` | the same for macOS on Intel (`os: ["darwin"]`, `cpu: ["x64"]`) |
+| `devsync-ai-darwin-arm64` | the same for macOS on Apple silicon (`os: ["darwin"]`, `cpu: ["arm64"]`) |
+
+Every package has the same version; a release publishes all five. Because each platform package declares `os` and `cpu`, npm, pnpm, yarn and bun install only the one that matches the machine and skip the rest without an error.
+
+The binaries have no runtime dependencies beyond the system's C library, so a clean machine needs only Node (to run the launcher) and Claude Code.
+
+### How `devsync` finds its binary
+
+`npm install -g devsync-ai` puts `devsync` on the PATH, pointing at `bin/devsync.js`. The launcher:
+
+1. maps `process.platform` and `process.arch` to a package name, `devsync-ai-<platform>-<arch>`;
+2. resolves `<that package>/bin/devsync` with `require.resolve`;
+3. runs it with the same arguments, stdin, stdout and stderr, and exits with its exit code (or re-raises its signal).
+
+The launcher runs the binary from its real path, not a copy or a symlink, because the binary finds things next to itself.
+
+### Where `devsync-hook` lands
+
+`devsync-hook` sits next to `devsync` in the platform package's `bin/`. It is not on the PATH. `devsync install-hooks` copies it from beside the running `devsync` to `~/.devsync/bin/devsync-hook` (or `$DEVSYNC_HOME/bin/devsync-hook`) and points Claude Code's hooks there, so upgrading or removing the npm package never breaks a running session's hooks. After an upgrade, run `devsync install-hooks` again to pick up the new hook.
+
+### Errors
+
+On a platform with no package (Windows, FreeBSD, Linux on 32-bit ARM, and so on) the launcher prints this and exits 1:
+
+```
+devsync: DevSync supports Linux and macOS (x64, arm64); this is <platform>-<arch>
+```
+
+When the platform is supported but its package is missing (installed with `--omit=optional` or `--no-optional`, or copied between machines), it prints this and exits 1:
+
+```
+devsync: devsync-ai-<platform>-<arch> is not installed. Reinstall without --omit=optional: npm install -g devsync-ai
+```
+
+When the binary is there but can't be run (lost its execute bit, wrong architecture under emulation), it prints the system error with the path, and exits 1:
+
+```
+devsync: can't run <path>: <error>
+```
+
+### Building, packing, publishing
+
+Agents build and pack; only the user publishes.
+
+```
+scripts/build.sh 1.2.3          # dist/<platform>/{devsync,devsync-hook} + dist/SHA256SUMS
+scripts/test-build.sh           # missing toolchains, reproducible host build, archs, no local paths
+scripts/pack.sh 1.2.3           # pack/devsync-ai-<platform>-1.2.3.tgz and pack/devsync-ai-1.2.3.tgz
+npm test                        # the launcher (node --test)
+```
+
+`build.sh` builds the host and the Linux targets; the macOS targets build only on a Mac, because linking them needs Apple's SDK (chrono's local time zone pulls in CoreFoundation). With no platforms named it builds `linux-x64` and `linux-arm64`, plus both `darwin-*` on a Mac. Linux targets other than the host need `cargo-zigbuild` and `zig` (its header says how to add them). A release tag builds all four on GitHub runners, macOS natively on a Mac (`.github/workflows/release.yml`). `pack.sh` checks each binary against `dist/SHA256SUMS` and pins every platform package to exactly the same version.
+
+To publish, platform packages first, so `devsync-ai`'s optional dependencies exist when it lands:
+
+```
+cd pack
+for p in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do npm publish devsync-ai-$p-1.2.3.tgz; done
+npm publish devsync-ai-1.2.3.tgz
+```

package/bin/devsync.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// The `devsync` command from npm: finds the binary in the platform package
+// npm installed for this machine (devsync-ai-<platform>-<arch>) and runs
+// it with the same arguments, stdin, stdout and stderr, then exits as it
+// did. See README.md, "Distribution".
+'use strict';
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+const PLATFORMS = {
+  'linux-x64': 'devsync-ai-linux-x64',
+  'linux-arm64': 'devsync-ai-linux-arm64',
+  'darwin-x64': 'devsync-ai-darwin-x64',
+  'darwin-arm64': 'devsync-ai-darwin-arm64',
+};
+
+/** The platform package for this platform and arch, or null. */
+function platformPackage(platform, arch) {
+  return PLATFORMS[`${platform}-${arch}`] || null;
+}
+
+/**
+ * The binary to run, as { binary } or { error } with the text to print.
+ * `resolve` is require.resolve (tests pass their own).
+ */
+function locate(platform, arch, resolve) {
+  const pkg = platformPackage(platform, arch);
+  if (!pkg) {
+    return {
+      error: `devsync: DevSync supports Linux and macOS (x64, arm64); this is ${platform}-${arch}`,
+    };
+  }
+  try {
+    // The package's own folder, then its binary: the real path, not a
+    // symlink, because devsync finds devsync-hook next to itself.
+    const dir = path.dirname(resolve(`${pkg}/package.json`));
+    return { binary: path.join(dir, 'bin', 'devsync') };
+  } catch {
+    return {
+      error: `devsync: ${pkg} is not installed. Reinstall without --omit=optional: npm install -g devsync-ai`,
+    };
+  }
+}
+
+/** Run `binary` with `args`, passing signals on, and exit as it does. */
+function run(binary, args) {
+  const child = spawn(binary, args, { stdio: 'inherit' });
+  const forward = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'];
+  const handlers = forward.map((sig) => {
+    const h = () => {
+      try {
+        child.kill(sig);
+      } catch {
+        // Already gone: its exit is on the way.
+      }
+    };
+    process.on(sig, h);
+    return [sig, h];
+  });
+  child.on('error', (e) => {
+    process.stderr.write(`devsync: can't run ${binary}: ${e.message}\n`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    for (const [sig, h] of handlers) process.removeListener(sig, h);
+    if (signal) {
+      // Die of the same signal, so the shell sees what the binary saw.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+function main() {
+  const found = locate(process.platform, process.arch, require.resolve);
+  if (found.error) {
+    process.stderr.write(`${found.error}\n`);
+    process.exit(1);
+  }
+  run(found.binary, process.argv.slice(2));
+}
+
+module.exports = { PLATFORMS, platformPackage, locate };
+
+if (require.main === module) {
+  main();
+}

package/package.json

@@ -1,8 +1,27 @@
 {
   "name": "devsync-ai",
-  "version": "0.0.1",
-  "description": "Name reservation for DevSync (devsync.ai): a neutral command surface for AI coding agents. Under development.",
+  "version": "0.1.0-rc.2",
+  "description": "DevSync (devsync.ai): one terminal screen over your coding-agent sessions, and the roadmap they work from.",
   "homepage": "https://devsync.ai",
-  "keywords": ["devsync", "ai", "coding-agents"],
-  "files": ["README.md"]
+  "keywords": [
+    "devsync",
+    "ai",
+    "coding-agents"
+  ],
+  "bin": {
+    "devsync": "bin/devsync.js"
+  },
+  "files": [
+    "bin/devsync.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "devsync-ai-linux-x64": "0.1.0-rc.2",
+    "devsync-ai-linux-arm64": "0.1.0-rc.2",
+    "devsync-ai-darwin-x64": "0.1.0-rc.2",
+    "devsync-ai-darwin-arm64": "0.1.0-rc.2"
+  }
 }