@wipcomputer/wip-ldm-os 0.4.72 → 0.4.73-alpha.10

package/bin/ldm.js

@@ -46,6 +46,53 @@ function installLog(msg) {
   } catch {}
 }
 
+// ── Semver comparison (#XX) ──
+// Proper semver comparison that handles prereleases correctly.
+// 0.4.73-alpha.1 > 0.4.72 (higher base version, prerelease doesn't matter)
+// 0.4.72-alpha.1 < 0.4.72 (same base version, prerelease is older than stable)
+// 0.4.73 > 0.4.72 (straightforward)
+// Returns true if version `a` is strictly newer than version `b`.
+function semverNewer(a, b) {
+  if (!a || !b || a === b) return false;
+  // Split into base and prerelease: "0.4.73-alpha.1" -> ["0.4.73", "alpha.1"]
+  const [aBase, aPre] = a.split('-', 2);
+  const [bBase, bPre] = b.split('-', 2);
+  const aParts = aBase.split('.').map(Number);
+  const bParts = bBase.split('.').map(Number);
+  // Compare base version (major.minor.patch)
+  for (let i = 0; i < 3; i++) {
+    const av = aParts[i] || 0;
+    const bv = bParts[i] || 0;
+    if (av > bv) return true;
+    if (av < bv) return false;
+  }
+  // Base versions are equal. Stable > prerelease.
+  // If a has no prerelease and b does, a is newer (stable release of same base).
+  // If a has prerelease and b doesn't, a is older (prerelease of same base).
+  if (!aPre && bPre) return true;   // a=0.4.72, b=0.4.72-alpha.1 -> a is newer
+  if (aPre && !bPre) return false;  // a=0.4.72-alpha.1, b=0.4.72 -> a is older
+  // Both have prereleases with same base. Compare prerelease segments lexically.
+  if (aPre && bPre) {
+    const aSegs = aPre.split('.');
+    const bSegs = bPre.split('.');
+    for (let i = 0; i < Math.max(aSegs.length, bSegs.length); i++) {
+      const as = aSegs[i] || '';
+      const bs = bSegs[i] || '';
+      // Numeric segments compared numerically
+      const an = /^\d+$/.test(as) ? Number(as) : NaN;
+      const bn = /^\d+$/.test(bs) ? Number(bs) : NaN;
+      if (!isNaN(an) && !isNaN(bn)) {
+        if (an > bn) return true;
+        if (an < bn) return false;
+      } else {
+        if (as > bs) return true;
+        if (as < bs) return false;
+      }
+    }
+  }
+  return false;
+}
+
 // Read our own version from package.json
 const pkgPath = join(__dirname, '..', 'package.json');
 let PKG_VERSION = '0.2.0';
@@ -148,6 +195,8 @@ const NONE_FLAG = args.includes('--none');
 const FIX_FLAG = args.includes('--fix');
 const CLEANUP_FLAG = args.includes('--cleanup');
 const CHECK_FLAG = args.includes('--check');
+const ALPHA_FLAG = args.includes('--alpha');
+const BETA_FLAG = args.includes('--beta');
 
 function readJSON(path) {
   try {
@@ -170,7 +219,7 @@ function checkCliVersion() {
       encoding: 'utf8',
       timeout: 10000,
     }).trim();
-    if (result && result !== PKG_VERSION) {
+    if (result && semverNewer(result, PKG_VERSION)) {
       console.log('');
       console.log(`  CLI is outdated: v${PKG_VERSION} installed, v${result} available.`);
       console.log(`  Run: npm install -g @wipcomputer/wip-ldm-os@${result}`);
@@ -1191,6 +1240,8 @@ async function cmdInstall() {
     --json       JSON output
     --yes        Auto-accept catalog prompts
     --none       Skip catalog prompts
+    --alpha      Check @alpha npm tag for updates (prerelease track)
+    --beta       Check @beta npm tag for updates (prerelease track)
 `);
     process.exit(0);
   }
@@ -1270,23 +1321,31 @@ async function cmdInstall() {
 
   // Check if target looks like an npm package (starts with @ or is a plain name without /)
   if (resolvedTarget.startsWith('@') || (!resolvedTarget.includes('/') && !existsSync(resolve(resolvedTarget)))) {
-    // Try npm install to temp dir
+    // Try npm pack + tar extract to temp dir
+    // npm install --prefix silently fails for scoped packages in temp directories...
+    // it creates the lock file but doesn't extract files. npm pack is reliable.
     const npmName = resolvedTarget;
     const tempDir = join(LDM_TMP, `npm-${Date.now()}`);
     console.log('');
     console.log(`  Installing ${npmName} from npm...`);
     try {
       mkdirSync(tempDir, { recursive: true });
-      execSync(`npm install ${npmName} --prefix "${tempDir}"`, { stdio: 'pipe' });
-      // Find the installed package in node_modules
-      const pkgName = npmName.startsWith('@') ? npmName : npmName;
-      const installed = join(tempDir, 'node_modules', pkgName);
-      if (existsSync(installed)) {
-        console.log(`  + Installed from npm`);
-        repoPath = installed;
+      // Use npm pack + tar instead of npm install --prefix
+      const tarball = execSync(`npm pack ${npmName} --pack-destination "${tempDir}" 2>/dev/null`, {
+        encoding: 'utf8', timeout: 60000, cwd: tempDir,
+      }).trim();
+      const tarPath = join(tempDir, tarball);
+      if (existsSync(tarPath)) {
+        execSync(`tar xzf "${tarPath}" -C "${tempDir}"`, { stdio: 'pipe' });
+        const extracted = join(tempDir, 'package');
+        if (existsSync(extracted)) {
+          console.log(`  + Installed from npm`);
+          repoPath = extracted;
+        } else {
+          console.error(`  x npm pack succeeded but extraction failed`);
+        }
       } else {
-        console.error(`  x Package installed but not found at expected path`);
-        process.exit(1);
+        console.error(`  x npm pack failed: tarball not found`);
       }
     } catch (e) {
       // npm failed, fall through to git clone or path resolution
@@ -1498,13 +1557,19 @@ async function cmdInstallCatalog() {
   // Self-update: check if CLI itself is outdated. Update first, then re-exec.
   // This breaks the chicken-and-egg: new features in ldm install are always
   // available because the installer upgrades itself before doing anything else.
+  // --alpha and --beta flags check the corresponding npm dist-tag instead of @latest.
   if (!DRY_RUN && !process.env.LDM_SELF_UPDATED) {
     try {
-      const latest = execSync('npm view @wipcomputer/wip-ldm-os version 2>/dev/null', {
+      const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+      const trackLabel = npmTag === 'latest' ? '' : ` (${npmTag} track)`;
+      const npmViewCmd = npmTag === 'latest'
+        ? 'npm view @wipcomputer/wip-ldm-os version 2>/dev/null'
+        : `npm view @wipcomputer/wip-ldm-os dist-tags.${npmTag} 2>/dev/null`;
+      const latest = execSync(npmViewCmd, {
         encoding: 'utf8', timeout: 15000,
       }).trim();
-      if (latest && latest !== PKG_VERSION) {
-        console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}. Updating first...`);
+      if (latest && semverNewer(latest, PKG_VERSION)) {
+        console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}${trackLabel}. Updating first...`);
         try {
           execSync(`npm install -g @wipcomputer/wip-ldm-os@${latest}`, { stdio: 'inherit', timeout: 60000 });
           console.log(`  CLI updated to v${latest}. Re-running with new code...`);
@@ -1761,7 +1826,7 @@ async function cmdInstallCatalog() {
     const cliLatest = execSync('npm view @wipcomputer/wip-ldm-os version 2>/dev/null', {
       encoding: 'utf8', timeout: 10000,
     }).trim();
-    if (cliLatest && cliLatest !== PKG_VERSION) {
+    if (cliLatest && semverNewer(cliLatest, PKG_VERSION)) {
       npmUpdates.push({
         name: 'LDM OS CLI',
         catalogNpm: '@wipcomputer/wip-ldm-os',
@@ -1819,13 +1884,18 @@ async function cmdInstallCatalog() {
     }
 
     // Check npm for updates (fast, one HTTP call)
+    // --alpha and --beta flags check the corresponding npm dist-tag
     if (npmPkg) {
       try {
-        const latestVersion = execSync(`npm view ${npmPkg} version 2>/dev/null`, {
+        const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+        const npmViewCmd = npmTag === 'latest'
+          ? `npm view ${npmPkg} version 2>/dev/null`
+          : `npm view ${npmPkg} dist-tags.${npmTag} 2>/dev/null`;
+        const latestVersion = execSync(npmViewCmd, {
           encoding: 'utf8', timeout: 10000,
         }).trim();
 
-        if (latestVersion && latestVersion !== currentVersion) {
+        if (latestVersion && semverNewer(latestVersion, currentVersion)) {
           npmUpdates.push({
             name,
             catalogRepo: repoUrl,
@@ -1852,7 +1922,7 @@ async function cmdInstallCatalog() {
         const tagMatch = tags.match(/refs\/tags\/v?(\d+\.\d+\.\d+)/);
         if (tagMatch) {
           const latestVersion = tagMatch[1];
-          if (latestVersion !== currentVersion) {
+          if (semverNewer(latestVersion, currentVersion)) {
             npmUpdates.push({
               name,
               catalogRepo: repoUrl,
@@ -1885,10 +1955,14 @@ async function cmdInstallCatalog() {
     if (!currentVersion) continue;
 
     try {
-      const latestVersion = execSync(`npm view ${catalogComp.npm} version 2>/dev/null`, {
+      const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+      const npmViewCmd = npmTag === 'latest'
+        ? `npm view ${catalogComp.npm} version 2>/dev/null`
+        : `npm view ${catalogComp.npm} dist-tags.${npmTag} 2>/dev/null`;
+      const latestVersion = execSync(npmViewCmd, {
         encoding: 'utf8', timeout: 10000,
       }).trim();
-      if (latestVersion && latestVersion !== currentVersion) {
+      if (latestVersion && semverNewer(latestVersion, currentVersion)) {
         npmUpdates.push({
           name: binName,
           catalogRepo: catalogComp.repo,
@@ -1921,7 +1995,7 @@ async function cmdInstallCatalog() {
       const latest = execSync(`npm view ${comp.npm} version 2>/dev/null`, {
         encoding: 'utf8', timeout: 10000,
       }).trim();
-      if (latest && latest !== currentVersion) {
+      if (latest && semverNewer(latest, currentVersion)) {
         // Remove any sub-tool entries that belong to this parent.
         const parentMatches = new Set(comp.registryMatches || []);
         for (let i = npmUpdates.length - 1; i >= 0; i--) {
@@ -2140,13 +2214,56 @@ async function cmdInstallCatalog() {
       continue;
     }
 
-    if (!entry.catalogRepo) {
+    if (!entry.catalogRepo && !entry.catalogNpm) {
       console.log(`  Skipping ${entry.name}: no catalog repo (install manually with ldm install <org/repo>)`);
       continue;
     }
-    console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+
+    // Source resolution chain (#264):
+    // 1. npm (when --alpha/--beta or npm package available) - works online, any machine
+    // 2. Local private repo (offline, developer machine) - works without internet
+    // 3. GitHub clone (fallback) - works online, any machine
+    let installSource = null;
+    const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : null;
+
+    // Try npm first when using alpha/beta tracks or when npm is available
+    if (entry.catalogNpm && (npmTag || !entry.catalogRepo)) {
+      const ver = npmTag ? `${entry.catalogNpm}@${npmTag}` : `${entry.catalogNpm}@${entry.latestVersion}`;
+      installSource = ver;
+      console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from npm ${npmTag || 'latest'})...`);
+    }
+
+    // Try local private repo (for offline/developer installs)
+    if (!installSource && entry.catalogRepo) {
+      const repoName = basename(entry.catalogRepo);
+      const privateRepoName = repoName + '-private';
+      const WORKSPACE = join(HOME, 'wipcomputerinc');
+      // Search known repo locations
+      const searchDirs = ['repos/ldm-os/devops', 'repos/ldm-os/components', 'repos/ldm-os/utilities', 'repos/ldm-os/apps', 'repos/ldm-os/apis', 'repos/ldm-os/identity'];
+      for (const dir of searchDirs) {
+        const localPrivate = join(WORKSPACE, dir, privateRepoName);
+        const localPublic = join(WORKSPACE, dir, repoName);
+        if (existsSync(localPrivate)) {
+          installSource = localPrivate;
+          console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from local ${privateRepoName})...`);
+          break;
+        }
+        if (existsSync(localPublic)) {
+          installSource = localPublic;
+          console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from local ${repoName})...`);
+          break;
+        }
+      }
+    }
+
+    // Fallback: GitHub clone
+    if (!installSource) {
+      installSource = entry.catalogRepo;
+      console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+    }
+
     try {
-      execSync(`ldm install ${entry.catalogRepo}`, { stdio: 'inherit' });
+      execSync(`ldm install ${installSource}`, { stdio: 'inherit' });
       updated++;
 
       // For parent packages, update registry version for all sub-tools (#139, #262)
@@ -2563,7 +2680,7 @@ function cmdStatus() {
     const latest = execSync('npm view @wipcomputer/wip-ldm-os version 2>/dev/null', {
       encoding: 'utf8', timeout: 10000,
     }).trim();
-    if (latest && latest !== PKG_VERSION) cliUpdate = latest;
+    if (latest && semverNewer(latest, PKG_VERSION)) cliUpdate = latest;
   } catch {}
 
   // Check extensions against npm using registry source info (#262)
@@ -2583,7 +2700,7 @@ function cmdStatus() {
       const latest = execSync(`npm view ${npmPkg} version 2>/dev/null`, {
         encoding: 'utf8', timeout: 10000,
       }).trim();
-      if (latest && latest !== currentVersion) {
+      if (latest && semverNewer(latest, currentVersion)) {
         updates.push({ name, current: currentVersion, latest, npm: npmPkg });
       }
     } catch {}

package/lib/deploy.mjs

@@ -394,14 +394,38 @@ function runBuildIfNeeded(repoPath) {
 
 function compareSemver(a, b) {
   if (!a || !b) return 0;
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
+  if (a === b) return 0;
+  const [aBase, aPre] = a.split('-', 2);
+  const [bBase, bPre] = b.split('-', 2);
+  const pa = aBase.split('.').map(Number);
+  const pb = bBase.split('.').map(Number);
   for (let i = 0; i < 3; i++) {
     const na = pa[i] || 0;
     const nb = pb[i] || 0;
     if (na > nb) return 1;
     if (na < nb) return -1;
   }
+  // Base versions equal. Stable > prerelease.
+  if (!aPre && bPre) return 1;   // a is stable, b is prerelease -> a is newer
+  if (aPre && !bPre) return -1;  // a is prerelease, b is stable -> b is newer
+  // Both have prereleases. Compare segments.
+  if (aPre && bPre) {
+    const aSegs = aPre.split('.');
+    const bSegs = bPre.split('.');
+    for (let i = 0; i < Math.max(aSegs.length, bSegs.length); i++) {
+      const as = aSegs[i] || '';
+      const bs = bSegs[i] || '';
+      const an = Number(as);
+      const bn = Number(bs);
+      if (!isNaN(an) && !isNaN(bn)) {
+        if (an > bn) return 1;
+        if (an < bn) return -1;
+      } else {
+        if (as > bs) return 1;
+        if (as < bs) return -1;
+      }
+    }
+  }
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.72",
+  "version": "0.4.73-alpha.10",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "engines": {

package/shared/docs/how-install-works.md.tmpl

@@ -16,11 +16,31 @@ Your AI reads the spec, explains what LDM OS is, checks if it's already installe
 1. **Self-update.** Checks npm for a newer version of itself. Updates first, then re-runs with new code.
 2. **System scan.** Reads `~/.ldm/extensions/`, `~/.openclaw/extensions/`, Claude Code MCP config, CLI binaries on PATH.
 3. **Catalog check.** Matches installed extensions against the catalog. Shows what's available, what's behind.
-4. **npm version check.** Checks every installed extension against npm for newer versions.
-5. **Update.** Clones from GitHub, builds if needed, deploys to extensions dirs, registers MCP/hooks/skills.
+4. **npm version check.** Checks every installed extension against npm for newer versions (uses dist-tags for alpha/beta).
+5. **Update.** Resolves the install source (see Source Resolution below), deploys to extensions dirs, registers MCP/hooks/skills.
 6. **Health check.** Verifies CLIs exist, no broken symlinks, no stale configs.
 7. **Cleanup.** Removes staging dirs, prunes ghost entries from registry.
 
+## Release Tracks
+
+```bash
+ldm install              # stable (npm @latest)
+ldm install --alpha      # alpha track (npm @alpha)
+ldm install --beta       # beta track (npm @beta)
+```
+
+Each track overwrites whatever is installed. Alpha, beta, and stable all use the same install path. The flag only changes which npm dist-tag is checked for updates.
+
+## Source Resolution
+
+When updating, the installer finds the package in priority order:
+
+1. **npm** (when `--alpha` or `--beta`): downloads from npm dist-tag. Works on any machine.
+2. **Local private repo** (developer machine): finds the repo at `~/wipcomputerinc/repos/ldm-os/`. Works offline, no npm or internet needed.
+3. **GitHub clone** (fallback): clones the public repo. Existing behavior.
+
+Alpha/beta installs never require `deploy-public`. Merge to private main, `wip-release alpha`, `ldm install --alpha`, done.
+
 ## Dry Run
 
 Always preview first:

package/shared/docs/how-releases-work.md.tmpl

@@ -1,77 +1,91 @@
 # How Releases Work
 
-## The Pipeline
+## Four Release Tracks
 
-Every release follows these steps. No shortcuts.
+| Track | npm tag | Who | Purpose |
+|-------|---------|-----|---------|
+| **Alpha** | `@alpha` | Developer | Moving fast. Fix, test, iterate. No deploy-public needed. |
+| **Beta** | `@beta` | Testers | Testing the distribution pipeline. npm + installer verified. |
+| **Hotfix** | `@latest` | Everyone | Emergency fix. Goes straight to stable. No deploy-public. |
+| **Stable** | `@latest` | Everyone | Full release. deploy-public syncs the public repo. |
 
-### 1. Branch and Code
+## The Alpha Flow (Development)
 
-Create a worktree, make your changes, commit:
-```bash
-ldm worktree add my-prefix/feature-name
-cd _worktrees/repo--my-prefix--feature-name/
-# edit files
-git add <files>
-git commit -m "description"
-```
-
-### 2. Write Release Notes
-
-Create `RELEASE-NOTES-v{version}.md` (dashes, not dots) in the repo root. Commit it on the branch with the code. It gets reviewed in the PR.
-
-### 3. Push and PR
+This is the fast path. Most work happens here.
 
 ```bash
-git push -u origin my-prefix/feature-name
-gh pr create --title "..." --body "..."
-gh pr merge --merge --delete-branch
-```
+# 1. Branch and code
+git worktree add .worktrees/repo--my-prefix--feature -b my-prefix/feature
+cd .worktrees/repo--my-prefix--feature/
+# edit, commit
 
-Never squash merge. Always `--merge`.
+# 2. Push, PR, merge
+git push -u origin my-prefix/feature
+gh pr create && gh pr merge --merge
 
-### 4. Release
+# 3. Alpha release
+cd /path/to/repo && git checkout main && git pull
+wip-release alpha --notes="what changed"
 
-```bash
-cd /path/to/repo    # main working tree, not worktree
-git checkout main && git pull
-wip-release patch   # auto-detects the release notes file
+# 4. Install and test
+ldm install --alpha
 ```
 
-`wip-release` handles: version bump, CHANGELOG.md, SKILL.md version sync, npm publish, GitHub release, website skill publish.
+Done. No deploy-public. No public repo sync. The installer pulls from npm @alpha (or finds the local private repo if offline).
 
-### 5. Deploy to Public
+**Sub-tool versions:** If you changed a sub-tool's code, bump its `package.json` version in the PR. Same version = same code. `wip-release` warns if files changed without a version bump.
+
+## The Stable Flow (Public Release)
 
 ```bash
-bash deploy-public.sh /path/to/private-repo org/public-repo
-```
+# 1-3. Same as alpha: branch, PR, merge
 
-Syncs everything except `ai/` to the public repo. Creates matching release with notes.
+# 4. Write release notes on the branch
+# RELEASE-NOTES-v{version}.md in repo root, committed with the code
 
-### 6. Install (Dogfood)
+# 5. Stable release
+git checkout main && git pull
+wip-release patch   # auto-detects release notes
 
-Open a new AI session and paste:
-```
-Read https://wip.computer/install/wip-ldm-os.txt
+# 6. Deploy to public
+deploy-public /path/to/private-repo org/public-repo
+
+# 7. Dogfood
+ldm install
 ```
 
-The AI walks through: explain, dry run, install. Never `npm install -g` directly.
+`wip-release` handles: version bump, CHANGELOG.md, SKILL.md sync, npm publish, GitHub release.
+
+`deploy-public` syncs everything except `ai/` to the public repo. Creates a matching release.
 
 ## Quality Gates
 
-`wip-release` enforces before publishing:
+`wip-release` enforces before publishing (stable only):
 - Release notes must be a file (not a flag)
-- Must reference a GitHub issue
 - Product docs must be updated
-- Technical docs must be updated if source changed
 - No stale merged branches
 - Must run from main working tree (not worktree)
 
+Alpha/beta skip most gates for speed.
+
+## Source Resolution
+
+The installer resolves sources in priority order:
+
+1. **npm** (with dist-tag for alpha/beta): works on any machine with internet
+2. **Local private repo**: works offline on developer machines
+3. **GitHub clone**: fallback for stable installs and third-party tools
+
+## Version Immutability
+
+Same version = same code. Always. If code changed, the version must change. The installer uses version comparison to decide whether to deploy. `wip-release` validates that sub-tools with changed files have bumped versions.
+
 ## Three Separate Steps
 
 | Step | What happens | What it means |
 |------|-------------|---------------|
 | Merge | PR merged to main | Code lands. Nothing else changes. |
-| Deploy | wip-release + deploy-public | Published to npm + GitHub. Not on your machine yet. |
-| Install | Run the install prompt | Extensions updated on your machine. |
+| Release | `wip-release alpha/beta/patch` | Published to npm. Available for install. |
+| Install | `ldm install [--alpha/--beta]` | Extensions updated on your machine. |
 
-After Deploy, stop. Don't copy files. Don't npm install. Dogfood the install prompt.
+For stable releases, add a fourth step: `deploy-public` to sync the public GitHub repo.