@ibgib/vcs-gib 0.0.6

package/README.md

@@ -0,0 +1,94 @@
+# @ibgib/vcs-gib
+
+> **Decentralized Version Control System (`ibgib` VCS)**
+> Built on content-addressed, cryptographic Merkle DAG hypergraphs (`ib^gib`).
+
+`vcs-gib` provides a zero-dependency, 100% in-band decentralized version control system CLI engine for human developers and autonomous AI coding agents.
+
+---
+
+## 🏛️ Architecture Highlights
+
+- **Multi-Space Branching (`b2s_<branchName>`)**: Every branch lives in its own dedicated local space inside `.vcsgib/ibgib/b2s_<branchName>/`, eliminating metastone timeline collisions (`tjp -> latest`) and enabling native space-to-space `SyncSaga` branch merging (`vcs merge`).
+- **Upward `.vcsgib` Discovery**: Commands run seamlessly from any subfolder or worktree directory (`cd b/feature-ui` or `cd src/`), walking parent directories to find the repository root (`repoRoot`).
+- **100% In-Band `ibgib` Graph Storage**: Repository index, active branch pointers, commit comments (`CommentIbGib_V1`), and binary payloads (`BinIbGib_V1`) are stored as immutable Merkle graph nodes.
+- **Zero 3rd-Party Runtime Dependencies**: Pure TypeScript/ESM implementation using native Node.js APIs and `@ibgib` monorepo packages.
+
+---
+
+## 📚 Quickstart & Documentation
+
+For the complete CLI user guide, command reference, worktree branching model, and step-by-step agent walkthroughs, see:
+
+👉 **[VCS CLI User & Agent Quickstart Guide](./VCS_CLI_USER_GUIDE.md)**
+
+---
+
+## ⚡ Global CLI Commands
+
+The CLI binary commands are globally available as **`ibgib`** and **`vcs`**:
+
+```bash
+# View command help
+ibgib --help
+
+# Initialize repository in current directory (creates b2s_main space in .vcsgib/ibgib/)
+ibgib init .
+
+# Check working tree status
+ibgib status
+
+# Stage untracked and modified files
+ibgib add -a
+
+# Commit snapshot with message
+ibgib commit -m "My commit message"
+
+# View commit timeline history
+ibgib log
+
+# List or create branches (populates b2s_<branchName> space via getDependencyGraph)
+ibgib branch feature-ui
+
+# Switch active branch and project worktree (b/feature-ui/)
+ibgib checkout feature-ui
+```
+
+---
+
+## 🏗️ Monorepo Build, Test & Package Workflows
+
+### 🧪 Unit & Integration Testing
+Run the single token-efficient respec test command from the monorepo root:
+
+```bash
+npm run test:vcs-gib
+```
+
+---
+
+### 📦 Isolated Downstream Testing & Hermetic Packaging (`build:for:test`)
+
+To eliminate global `npm link` pollution and prepare for hermetic, dockerized downstream CI testing, `vcs-gib` provides a automated packaging pipeline.
+
+#### Purpose of Isolated Testing:
+- Prevents `npm link` from contaminating global system state or interfering with monorepo dependencies.
+- Bumps the patch version (`0.0.x`), compiles `vcs-gib`, generates an npm tarball (`.tgz`), and deploys it to an isolated downstream testing workspace (`test_repos/packages/`).
+
+#### How to Execute:
+From the monorepo root:
+
+```bash
+# Run the test packaging pipeline (or 'npm run build:vcs-gib:test')
+npm run build:for:test
+```
+
+#### Environment Variable Configuration:
+The target destination directory can be configured in your root `.env` file or environment:
+
+```env
+VCS_GIB_TEST_PACKAGE_DIR="c:\Users\billm\antigravity\test_repos\packages"
+```
+
+#### Downstream Execution Note:
+> 💡 **Next Step**: After executing `npm run build:for:test`, navigate to your downstream `test_repos` workspace (`c:\Users\billm\antigravity\test_repos\`) and execute automated `respec-gib` integration test suites against `vcs-gib-latest.tgz` (or specific versioned tarball `vcs-gib-0.0.x.tgz`) as needed!

package/VCS_CLI_USER_GUIDE.md

@@ -0,0 +1,198 @@
+# 🚀 `ibgib` VCS CLI - User & Agent Quickstart Guide
+
+Welcome to the **`ibgib` Version Control System (VCS)** CLI!
+
+`ibgib` VCS is a next-generation decentralized version control system built on a content-addressed, cryptographic Merkle DAG hypergraph (`ib^gib`). Unlike traditional Git, **100% of repository state, branch pointers, commit graphs, and staged indices live in-band as immutable `ibgib` graph nodes**.
+
+The global CLI executable command is **`ibgib`** (or its alias **`vcs`**).
+
+---
+
+## 🏛️ Key Architectural Features
+
+1. **Multi-Space Branching (`b2s_<branchName>`)**:
+   - Each branch lives in its own dedicated local space inside `.vcsgib/ibgib/b2s_<branchName>/`.
+   - **Zero Metastone Timeline Collisions**: Each branch tracks its own file timeline tips (`tjp -> latest`) cleanly.
+   - **Native Space-to-Space Merging**: Branch merging (`vcs merge`) uses `SyncSagaCoordinator` natively space-to-space out of the box.
+2. **Upward `.vcsgib` Discovery**:
+   - Running `ibgib` commands inside any subfolder or worktree directory (e.g. `cd b/feature-login` or `cd src/`) automatically walks parent directories (`path.dirname`) to find `.vcsgib` and locate the repository root (`repoRoot`).
+3. **1-to-1 Worktree Alignment**:
+   - Root folder `my-repo/` $\longleftrightarrow$ Space `b2s_main`.
+   - Subfolder `my-repo/b/<branch>/` $\longleftrightarrow$ Space `b2s_<branch>`.
+
+---
+
+## 📦 Testing & Package Build Workflow
+
+The repository uses an isolated, hermetic downstream packaging workflow (`build:for:test`):
+
+```bash
+# Build vcs-gib, bump patch version, pack tarball, and deploy to downstream test_repos/packages/
+npm run build:for:test
+```
+
+After executing `npm run build:for:test`, navigate to `c:\Users\billm\antigravity\test_repos\` and run automated integration test suites against `vcs-gib-latest.tgz`.
+
+---
+
+## 🛠️ Command Reference Summary
+
+| Command | Syntax | Description | Example |
+| :--- | :--- | :--- | :--- |
+| **`init`** | `ibgib init [dir]` | Initializes a new `ibgib` repository in target directory. Scopes `.vcsgib/ibgib/b2s_main/` space, root folder node, `main` branch, and in-band index. | `ibgib init .`<br>`ibgib init my-repo` |
+| **`status`** | `ibgib status` | Displays working tree status: untracked files, modified files, deleted files, and staged items on active branch space (`b2s_<activeBranch>`). Works from root or subfolders. | `ibgib status` |
+| **`add`** | `ibgib add <path...>`<br>`ibgib add -a` | Stages file/folder candidate nodes and binary payloads into active branch space index (`B2tFSIndexIbGib_V1`). Use `-a` or `--all` to stage everything. | `ibgib add src/index.ts`<br>`ibgib add -a` |
+| **`commit`** | `ibgib commit -m "msg"` | Records snapshot changes in active branch space, creates an in-band commit comment (`CommentIbGib_V1`), advances branch tip, and clears index staging. | `ibgib commit -m "Initial commit"` |
+| **`log`** | `ibgib log` | Displays formatted commit history walking backward along active branch timeline (`past` / `ancestor` rel8ns). | `ibgib log` |
+| **`branch`** | `ibgib branch [name]` | Omitted `name`: lists registered branches.<br>Provided `name`: creates dedicated branch space `b2s_<name>`, populates graph nodes via `getDependencyGraph`, and registers `B2tFSBranchIbGib_V1`. | `ibgib branch`<br>`ibgib branch feature-ui` |
+| **`checkout`** | `ibgib checkout <branch>` | Switches active branch in index and materializes branch snapshot onto target worktree directory (`my-repo/` if main, `b/<branch>/` if secondary). | `ibgib checkout main`<br>`ibgib checkout feature-ui` |
+
+---
+
+## 📁 Repository Directory Structure & Worktree Model
+
+When you run `ibgib init my-repo`, the directory layout operates as follows:
+
+```text
+my-repo/
+├── .vcsgib/                   <-- Hardcoded ignored metadata folder
+│   ├── ibgib/                 <-- LocalSpace graph storage for branch spaces
+│   │   ├── 000_zerospace/    <-- Metaspace registry
+│   │   ├── b2s_main/          <-- Space for 'main' branch
+│   │   └── b2s_feature-ui/    <-- Space for 'feature-ui' branch
+│   └── vcs_index_projection.json <-- Read-only index projection cache
+├── b/                         <-- Reserved branch worktrees directory
+│   ├── feature-ui/            <-- Projected worktree for branch 'feature-ui'
+│   │   └── app.ts
+│   └── feature-auth/          <-- Projected worktree for branch 'feature-auth'
+│       └── auth.ts
+├── src/                       <-- Source code files (tracked on 'main' branch)
+│   └── main.ts
+└── .ibgibignore               <-- Optional user ignore filter file
+```
+
+### Key Worktree Rules:
+1. **Primary Workspace (`main`)**: The root folder `my-repo/` is the active physical workspace for `main`.
+2. **Secondary Branch Worktrees (`b/<branch>/`)**: When you create and check out a secondary branch (e.g. `feature-ui`), its projected workspace files live under `my-repo/b/feature-ui/`.
+3. **Upward Discovery**: You can run `ibgib status`, `ibgib add`, `ibgib commit` directly inside `b/feature-ui/` or `src/`. `ibgib` automatically discovers `.vcsgib` in the parent directory tree.
+4. **Hardcoded Reserved Ignored Paths**:
+   The following paths are **automatically ignored** during workspace scans regardless of `.ibgibignore`:
+   - `.vcsgib` (in-band metadata and localSpace graph storage)
+   - `b` (secondary branch worktree folder)
+   - `ibgib` (zerospace metadata cache)
+   - `node_modules`
+   - `.git`
+
+---
+
+## 🚫 `.ibgibignore` File Filter Semantics
+
+You can place an optional `.ibgibignore` file in your repository root. Standard `.gitignore` rules apply:
+
+```gitignore
+# Ignore log files and build outputs
+*.log
+dist/
+temp/
+
+# Negation rule (include specific file)
+!important.log
+```
+
+---
+
+## 🤖 Step-by-Step Walkthrough for AI Agents & Humans
+
+Here is a complete, copy-pasteable CLI session demonstrating how to use `ibgib`:
+
+### Step 1: Create and initialize repository
+```bash
+# Create directory and initialize ibgib repository
+mkdir my-app
+cd my-app
+ibgib init .
+```
+*Output:* Initialized empty ibgib repository at `my-app` (spaceId: `b2s_main`, activeBranch: `main`).
+
+---
+
+### Step 2: Create files and check status
+```bash
+# Create initial source files
+echo 'console.log("Hello ibgib!");' > index.ts
+echo 'export const version = "1.0.0";' > config.ts
+
+# Check status
+ibgib status
+```
+*Output:* Shows `index.ts` and `config.ts` under **Untracked files**.
+
+---
+
+### Step 3: Stage and commit files
+```bash
+# Stage all files
+ibgib add -a
+
+# Commit snapshot with message
+ibgib commit -m "Add initial index.ts and config.ts"
+```
+*Output:* Commits snapshot into `b2s_main` space, creates `CommentIbGib_V1` node, and advances `main` branch tip.
+
+---
+
+### Step 4: View commit history
+```bash
+ibgib log
+```
+*Output:* Displays commit hash, timestamp, comment message (`Add initial index.ts and config.ts`), and author.
+
+---
+
+### Step 5: Create a new branch and checkout
+```bash
+# Create new feature branch (populates b2s_feature-login space via getDependencyGraph)
+ibgib branch feature-login
+
+# Switch to feature branch
+ibgib checkout feature-login
+```
+*Output:* Switches active branch to `feature-login` and projects branch files into `b/feature-login/`.
+
+---
+
+### Step 6: Make changes in feature branch worktree
+```bash
+# Navigate into feature branch worktree
+cd b/feature-login
+
+# Add feature login file
+echo 'export function login() { return true; }' > login.ts
+
+# Check status (Upward discovery finds .vcsgib and targets b2s_feature-login space!)
+ibgib status
+
+# Stage and commit in feature branch
+ibgib add -a
+ibgib commit -m "Implement login helper"
+```
+
+---
+
+### Step 7: Switch back to main branch
+```bash
+# Return to repository root
+cd ../..
+
+# Switch back to main branch
+ibgib checkout main
+```
+*Output:* Active branch set back to `main`. `my-repo/` working tree reflects `main` snapshot.
+
+---
+
+## 💡 Key Design Guarantees for AI Agents
+
+1. **Deterministic Execution**: Every CLI command completes synchronously and outputs clear, structured status messages.
+2. **Zero 3rd-Party Runtime Dependencies**: All commands run natively on Node.js using internal `@ibgib/*` packages.
+3. **In-Band Merkle Links**: All commit nodes, items, and binary file payloads are cryptographically hashed as composite `ib^gib` addresses (`v1^ib^gib`).

package/dist/AUTO-GENERATED-version.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @module AUTO-GENERATED-version
+ * Auto-generated version constant. Do NOT edit directly.
+ */
+export declare const AUTO_GENERATED_VERSION = "0.0.6";
+//# sourceMappingURL=AUTO-GENERATED-version.d.mts.map

package/dist/AUTO-GENERATED-version.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AUTO-GENERATED-version.d.mts","sourceRoot":"","sources":["../src/AUTO-GENERATED-version.mts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC"}

package/dist/AUTO-GENERATED-version.mjs

@@ -0,0 +1,6 @@
+/**
+ * @module AUTO-GENERATED-version
+ * Auto-generated version constant. Do NOT edit directly.
+ */
+export const AUTO_GENERATED_VERSION = '0.0.6';
+//# sourceMappingURL=AUTO-GENERATED-version.mjs.map

package/dist/AUTO-GENERATED-version.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"AUTO-GENERATED-version.mjs","sourceRoot":"","sources":["../src/AUTO-GENERATED-version.mts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC"}

package/dist/assumptions.respec.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=assumptions.respec.d.mts.map

package/dist/assumptions.respec.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.respec.d.mts","sourceRoot":"","sources":["../src/assumptions.respec.mts"],"names":[],"mappings":""}

package/dist/assumptions.respec.mjs

@@ -0,0 +1,41 @@
+import { ifWe, iReckon, respecfully } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+/**
+ * wrapper that uses crypto.subtle under the hood (i.e. doesn't hash using ts-gib)
+ *
+ * notes:
+ *
+ * * i did in fact copy this from ts-gib though, but we're testing simply that the
+ *   context (node/browser/whatever) has this since it's integral to all things ibgib.
+ */
+async function cryptoSubtleHash({ s, algorithm = 'SHA-256', }) {
+    let { subtle } = globalThis.crypto;
+    if (!s) {
+        throw new Error(`[${cryptoSubtleHash.name}] s is required`);
+    }
+    if (!algorithm) {
+        throw new Error(`[${cryptoSubtleHash.name}] algorithm is required`);
+    }
+    try {
+        const msgUint8 = new TextEncoder().encode(s);
+        const buffer = await subtle.digest(algorithm, msgUint8);
+        const asArray = Array.from(new Uint8Array(buffer));
+        return asArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    catch (e) {
+        console.error(e.message ?? e);
+        throw e;
+    }
+}
+await respecfully(sir, `non-ts-gib isomorphic crypto hashing`, async () => {
+    await ifWe(sir, `should digest simple string consistently using crypto.subtle directly `, async () => {
+        let h = await cryptoSubtleHash({ s: '42' });
+        iReckon(sir, h).asTo('42').isGonnaBe('73475cb40a568e8da8a045ced110137e159f890ac4da883b6b17dc651b3a8049');
+    });
+    await ifWe(sir, `should digest simple stringified ibgib consistently using crypto.subtle directly `, async () => {
+        let ibgib = { ib: 'ib', gib: 'gib' };
+        let h = await cryptoSubtleHash({ s: JSON.stringify(ibgib) }); // doesn't use ts-gib but consistent stringifying json is important
+        iReckon(sir, h).asTo('ib^gib').isGonnaBe('cbad0694a257358c044611ea1fa88ace71a01a9b8409d2354d0387d8043f7671');
+    });
+});
+//# sourceMappingURL=assumptions.respec.mjs.map

package/dist/assumptions.respec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.respec.mjs","sourceRoot":"","sources":["../src/assumptions.respec.mts"],"names":[],"mappings":"AAAA,OAAO,EACH,IAAI,EAAE,OAAO,EAAE,WAAW,EAC7B,MAAM,kDAAkD,CAAC;AAG1D,MAAM,IAAI,GAAG,IAAI,OAAO,IAAI,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;AAEhD;;;;;;;GAOG;AACH,KAAK,UAAU,gBAAgB,CAAC,EAC5B,CAAC,EACD,SAAS,GAAG,SAAS,GAIxB;IACG,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC;IACnC,IAAI,CAAC,CAAC,EAAE,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,IAAI,gBAAgB,CAAC,IAAI,iBAAiB,CAAC,CAAA;IAAC,CAAC;IACvE,IAAI,CAAC,SAAS,EAAE,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,IAAI,gBAAgB,CAAC,IAAI,yBAAyB,CAAC,CAAA;IAAC,CAAC;IACvF,IAAI,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC;IACZ,CAAC;AACL,CAAC;AAED,MAAM,WAAW,CAAC,GAAG,EAAE,sCAAsC,EAAE,KAAK,IAAI,EAAE;IAEtE,MAAM,IAAI,CAAC,GAAG,EAAE,wEAAwE,EAAE,KAAK,IAAI,EAAE;QACjG,IAAI,CAAC,GAAG,MAAM,gBAAgB,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,kEAAkE,CAAC,CAAC;IAC7G,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,GAAG,EAAE,mFAAmF,EAAE,KAAK,IAAI,EAAE;QAC5G,IAAI,KAAK,GAAa,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/C,IAAI,CAAC,GAAG,MAAM,gBAAgB,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,mEAAmE;QACjI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,kEAAkE,CAAC,CAAC;IACjH,CAAC,CAAC,CAAC;AAEP,CAAC,CAAC,CAAC"}

package/dist/bootstrap/node-bootstrap.d.mts

@@ -0,0 +1,35 @@
+/**
+ * @module node-bootstrap
+ *
+ * Rapid Node Metaspace bootstrap helper aligned with space-gib startup principles.
+ * Moves execution from CLI start to "ibgib environment" rapidly without process.chdir() hacks.
+ */
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { Metaspace_Nodespace } from '@ibgib/node-gib/dist/witness/space/metaspace/metaspace-nodespace/metaspace-nodespace.mjs';
+export interface BootstrapVcsMetaspaceOpts {
+    /**
+     * Absolute or relative path to target repository directory. Defaults to process.cwd()
+     */
+    repoPath?: string;
+    /**
+     * Subfolder for vcs-gib metadata storage. Defaults to '.vcsgib'
+     */
+    vcsFolderName?: string;
+    /**
+     * Default space name for non-interactive headless testing. Defaults to 'vcs_space'
+     */
+    defaultSpaceName?: string;
+}
+export interface BootstrapVcsMetaspaceResult {
+    metaspace: Metaspace_Nodespace;
+    localSpace: IbGibSpaceAny;
+    vcsPath: string;
+    repoRoot: string;
+}
+/**
+ * Bootstraps Metaspace_Nodespace and initializes the local repository space.
+ * Moves execution into the ibgib environment rapidly without process.chdir() directory hacks.
+ * Performs upward discovery of .vcsgib metadata folder.
+ */
+export declare function bootstrapVcsMetaspace(opts?: BootstrapVcsMetaspaceOpts): Promise<BootstrapVcsMetaspaceResult>;
+//# sourceMappingURL=node-bootstrap.d.mts.map

package/dist/bootstrap/node-bootstrap.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-bootstrap.d.mts","sourceRoot":"","sources":["../../src/bootstrap/node-bootstrap.mts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,aAAa,EAAE,MAAM,sDAAsD,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0FAA0F,CAAC;AAU/H,MAAM,WAAW,yBAAyB;IACtC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IACxC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,aAAa,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACvC,IAAI,GAAE,yBAA8B,GACrC,OAAO,CAAC,2BAA2B,CAAC,CAgJtC"}

package/dist/bootstrap/node-bootstrap.mjs

@@ -0,0 +1,165 @@
+/**
+ * @module node-bootstrap
+ *
+ * Rapid Node Metaspace bootstrap helper aligned with space-gib startup principles.
+ * Moves execution from CLI start to "ibgib environment" rapidly without process.chdir() hacks.
+ */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { clone, delay } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getGib } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { updateBootstrapIbGib } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { Metaspace_Nodespace } from '@ibgib/node-gib/dist/witness/space/metaspace/metaspace-nodespace/metaspace-nodespace.mjs';
+import { NodeFilesystemSpace_V1 } from '@ibgib/node-gib/dist/witness/space/node-filesystem-space/node-filesystem-space-v1.mjs';
+import { DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1 } from '@ibgib/node-gib/dist/witness/space/node-filesystem-space/node-filesystem-space-types.mjs';
+import { fnCreateNewLocalSpace, fnDtoToSpace_nodeFilesystem } from '@ibgib/node-gib/dist/witness/space/metaspace/metaspace-nodespace/metaspace-nodespace-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../vcs-gib-constants.mjs';
+const lcFile = `[node-bootstrap]`;
+const logalot = GLOBAL_LOG_A_LOT;
+/**
+ * Bootstraps Metaspace_Nodespace and initializes the local repository space.
+ * Moves execution into the ibgib environment rapidly without process.chdir() directory hacks.
+ * Performs upward discovery of .vcsgib metadata folder.
+ */
+export async function bootstrapVcsMetaspace(opts = {}) {
+    const lc = `${lcFile}[${bootstrapVcsMetaspace.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 9f8a0b1c2d3e4f5a6b7c8d9e0f1a2b3c)`);
+        }
+        const { repoPath = process.cwd(), vcsFolderName = '.vcsgib', } = opts;
+        let currentDir = path.resolve(repoPath);
+        let foundVcsPath;
+        let repoRoot = currentDir;
+        while (true) {
+            const candidateVcsPath = path.join(currentDir, vcsFolderName);
+            let exists = false;
+            try {
+                const stat = await fs.stat(candidateVcsPath);
+                if (stat.isDirectory()) {
+                    exists = true;
+                }
+            }
+            catch {
+                exists = false;
+            }
+            if (exists) {
+                foundVcsPath = candidateVcsPath;
+                repoRoot = currentDir;
+                break;
+            }
+            const parentDir = path.dirname(currentDir);
+            if (parentDir === currentDir) {
+                break;
+            }
+            currentDir = parentDir;
+        }
+        const vcsPath = foundVcsPath || path.resolve(repoPath, vcsFolderName);
+        if (!foundVcsPath) {
+            repoRoot = path.resolve(repoPath);
+        }
+        const safeRepoDir = path.basename(repoRoot).replace(/[^a-zA-Z0-9_\-]/g, '_');
+        const defaultSpaceName = opts.defaultSpaceName || `vcs_${safeRepoDir}`;
+        if (logalot) {
+            console.log(`${lc} initializing vcsMetaspace at vcsPath: ${vcsPath}, repoRoot: ${repoRoot} (I: 4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d)`);
+        }
+        // Read localSpaceId from index projection if repository has been initialized
+        let localSpaceId;
+        try {
+            const projFile = path.join(vcsPath, 'vcs_index_projection.json');
+            const projRaw = await fs.readFile(projFile, 'utf8');
+            const projData = JSON.parse(projRaw);
+            if (projData && projData.spaceId) {
+                localSpaceId = projData.spaceId;
+            }
+        }
+        catch {
+            // Projection file missing before init
+        }
+        // Instantiate Metaspace_Nodespace
+        const metaspace = new Metaspace_Nodespace(undefined);
+        metaspace.fnUpdateBootstrap = async (newSpace) => {
+            await updateBootstrapIbGib({ zeroSpace: metaspace.zeroSpace, space: newSpace });
+        };
+        await metaspace.initialize({
+            spaceName: defaultSpaceName,
+            metaspaceFactory: {
+                fnZeroSpaceFactory: () => {
+                    const zeroSpaceData = {
+                        ...clone(DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1),
+                        baseDir: vcsPath,
+                    };
+                    const zeroSpace = new NodeFilesystemSpace_V1(zeroSpaceData);
+                    zeroSpace.gib = 'gib';
+                    return zeroSpace;
+                },
+                fnDefaultLocalSpaceFactory: async (spaceOpts) => {
+                    const space = await fnCreateNewLocalSpace(spaceOpts);
+                    if (space && space.data) {
+                        space.data.baseDir = vcsPath;
+                        space.gib = await getGib({ ibGib: space, hasTjp: true });
+                    }
+                    return space;
+                },
+                fnDtoToSpace: async (spaceDto) => {
+                    const space = await fnDtoToSpace_nodeFilesystem(spaceDto);
+                    if (space && space.data) {
+                        space.data.baseDir = vcsPath;
+                    }
+                    return space;
+                },
+            },
+            getFnAlert: () => async ({ title, msg }) => {
+                if (logalot) {
+                    console.log(`${lc} [Alert] ${title}: ${msg} (I: 7e6f5d4c3b2a1f0e9d8c7b6a5f4e3d2c)`);
+                }
+            },
+            getFnPrompt: () => async ({ title, msg }) => {
+                if (logalot) {
+                    console.log(`${lc} [Prompt] ${title}: ${msg} (I: 2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e)`);
+                }
+                return defaultSpaceName;
+            },
+            getFnPromptPassword: () => async (title, msg) => {
+                if (logalot) {
+                    console.log(`${lc} [PromptPwd] ${title}: ${msg} (I: 5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c)`);
+                }
+                return null;
+            },
+        });
+        while (!metaspace.initialized) {
+            await delay(10);
+        }
+        const localSpace = await metaspace.getLocalUserSpace({
+            localSpaceId,
+            lock: false,
+        });
+        if (!localSpace) {
+            throw new Error(`Failed to initialize localUserSpace in metaspace (E: 8192a472c9104b2c)`);
+        }
+        if (localSpace.data && localSpace.data.baseDir !== vcsPath) {
+            localSpace.data.baseDir = vcsPath;
+        }
+        await localSpace.initialized;
+        if (logalot) {
+            const spaceName = localSpace.data?.name || localSpace.ib;
+            console.log(`${lc} Metaspace ready. LocalSpace name/ib: ${spaceName} (I: 1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f)`);
+        }
+        return {
+            metaspace,
+            localSpace,
+            vcsPath,
+            repoRoot,
+        };
+    }
+    catch (error) {
+        console.error(`${lc} ${error?.message || error} (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+        throw error;
+    }
+    finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a)`);
+        }
+    }
+}
+//# sourceMappingURL=node-bootstrap.mjs.map

package/dist/bootstrap/node-bootstrap.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-bootstrap.mjs","sourceRoot":"","sources":["../../src/bootstrap/node-bootstrap.mts"],"names":[],"mappings":"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"}

package/dist/bootstrap/node-bootstrap.respec.node.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @module node-bootstrap.respec
+ *
+ * Unit tests for rapid Node Metaspace bootstrap helper.
+ */
+export {};
+//# sourceMappingURL=node-bootstrap.respec.node.d.mts.map

package/dist/bootstrap/node-bootstrap.respec.node.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-bootstrap.respec.node.d.mts","sourceRoot":"","sources":["../../src/bootstrap/node-bootstrap.respec.node.mts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/bootstrap/node-bootstrap.respec.node.mjs

@@ -0,0 +1,28 @@
+/**
+ * @module node-bootstrap.respec
+ *
+ * Unit tests for rapid Node Metaspace bootstrap helper.
+ */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { respecfully, ifWe, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { bootstrapVcsMetaspace } from './node-bootstrap.mjs';
+const lc = `[apps/vcs-gib/src/bootstrap/node-bootstrap.respec.node.mts]`;
+await respecfully(lc, `Node Metaspace Bootstrap`, async () => {
+    await ifWe(lc, `bootstraps metaspace and local space rapidly without errors`, async () => {
+        const testDir = path.join(process.cwd(), '.test_bootstrap_repo');
+        try {
+            const { metaspace, localSpace, vcsPath } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName: '.vcsgib_test',
+            });
+            iReckon(lc, metaspace.initialized).isGonnaBeTrue();
+            iReckon(lc, localSpace).isGonnaBeTruthy();
+            iReckon(lc, vcsPath).includes('.vcsgib_test');
+        }
+        finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=node-bootstrap.respec.node.mjs.map

package/dist/bootstrap/node-bootstrap.respec.node.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-bootstrap.respec.node.mjs","sourceRoot":"","sources":["../../src/bootstrap/node-bootstrap.respec.node.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,OAAO,EACH,WAAW,EAAE,IAAI,EAAE,OAAO,EAC7B,MAAM,kDAAkD,CAAC;AAE1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,EAAE,GAAG,6DAA6D,CAAC;AAEzE,MAAM,WAAW,CAAC,EAAE,EAAE,0BAA0B,EAAE,KAAK,IAAI,EAAE;IAEzD,MAAM,IAAI,CAAC,EAAE,EAAE,6DAA6D,EAAE,KAAK,IAAI,EAAE;QACrF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,sBAAsB,CAAC,CAAC;QACjE,IAAI,CAAC;YACD,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,qBAAqB,CAAC;gBACnE,QAAQ,EAAE,OAAO;gBACjB,aAAa,EAAE,cAAc;aAChC,CAAC,CAAC;YAEH,OAAO,CAAC,EAAE,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,aAAa,EAAE,CAAC;YACnD,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,eAAe,EAAE,CAAC;YAC1C,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAClD,CAAC;gBAAS,CAAC;YACP,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/cli/cli-arg-parser.d.mts

@@ -0,0 +1,27 @@
+/**
+ * @module cli-arg-parser
+ *
+ * Native, zero-dependency command line argument parser for vcs CLI commands.
+ * Refactored to use RCLIParamInfo constants and VCS_SUBCOMMANDS definitions.
+ */
+import { VCS_SUBCOMMANDS } from './cli-constants.mjs';
+export type VcsSubcommand = typeof VCS_SUBCOMMANDS[keyof typeof VCS_SUBCOMMANDS];
+export interface ParsedVcsArgs {
+    command: VcsSubcommand;
+    positionals: string[];
+    flags: {
+        message?: string;
+        branchName?: string;
+        all?: boolean;
+        force?: boolean;
+        verbose?: boolean;
+        help?: boolean;
+        shareIgnored?: boolean;
+    };
+    rawArgs: string[];
+}
+/**
+ * Parses raw command line argument vector (process.argv.slice(2)).
+ */
+export declare function parseVcsArgs(argv: string[]): ParsedVcsArgs;
+//# sourceMappingURL=cli-arg-parser.d.mts.map