@ibgib/vcs-gib 0.0.6

package/dist/vcs-gib.respec.node.d.mts.map

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

package/dist/vcs-gib.respec.node.mjs

@@ -0,0 +1,82 @@
+/**
+ * @module vcs-gib.respec.node
+ *
+ * Full Engine Cycle Integration Tests for @ibgib/vcs-gib.
+ * Tests Metaspace bootstrap, canonical ib atoms, item creation, branch spaces, and index tracking.
+ */
+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 { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { bootstrapVcsMetaspace } from './bootstrap/node-bootstrap.mjs';
+import { getB2tFSItemIb } from './engine/item/item-atom-helper.mjs';
+import { createB2tFSBranchIbGib, getB2tFSBranchSpaceName } from './engine/branch/branch-helper.mjs';
+import { createB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr, parseSpaceQualifiedIbGibAddr } from './engine/index/index-helper.mjs';
+const lc = `[apps/vcs-gib/src/vcs-gib.respec.node.mts]`;
+await respecfully(lc, `vcs-gib Full Engine Cycle`, async () => {
+    await respecfully(lc, `Canonical ib Atoms`, async () => {
+        await ifWe(lc, `formats canonical space-delimited ib atom strings`, async () => {
+            const ib = getB2tFSItemIb('file', 'index.mts', 'hash123');
+            iReckon(lc, ib).includes('b2tfs_item file index.mts v1 hash123');
+        });
+    });
+    await respecfully(lc, `Space-Qualified Addresses`, async () => {
+        await ifWe(lc, `formats and parses space-qualified addresses`, async () => {
+            const sq = getSpaceQualifiedIbGibAddr('space_a', 'item^gib123');
+            iReckon(lc, sq).willEqual('v:1^spaceId:space_a^item^gib123');
+            const parsed = parseSpaceQualifiedIbGibAddr(sq);
+            iReckon(lc, parsed?.spaceId).willEqual('space_a');
+            iReckon(lc, parsed?.ibGibAddr).willEqual('item^gib123');
+        });
+    });
+    await respecfully(lc, `Branch Spaces & Index Tracking`, async () => {
+        await ifWe(lc, `initializes metaspace, creates branch, and registers index`, async () => {
+            const testDir = path.join(process.cwd(), '.test_cycle_repo');
+            try {
+                const { metaspace, localSpace } = await bootstrapVcsMetaspace({
+                    repoPath: testDir,
+                    vcsFolderName: '.vcsgib_cycle_test',
+                    defaultSpaceName: 'test_space',
+                });
+                // Create root folder item
+                const itemRes = await Factory_V1.firstGen({
+                    parentIbGib: ROOT,
+                    ib: getB2tFSItemIb('folder', 'root', 'root_hash'),
+                    data: {
+                        name: 'root',
+                        nameHash: 'root_hash',
+                        fsType: 'folder',
+                        diffTransactionId: 'tx_123',
+                    }
+                });
+                const rootItem = itemRes.newIbGib;
+                // Create Branch IbGib
+                const branchName = 'main';
+                const branchSpaceName = getB2tFSBranchSpaceName(branchName);
+                iReckon(lc, branchSpaceName).willEqual('b2s_main');
+                const branchIbGib = await createB2tFSBranchIbGib({
+                    branchName,
+                    rootItem,
+                    space: localSpace,
+                    metaspace,
+                });
+                iReckon(lc, branchIbGib.data?.name).willEqual('main');
+                // Create Index IbGib
+                const indexIbGib = await createB2tFSIndexIbGib({
+                    spaceId: 'local_space_uuid',
+                    activeSpaceId: 'local_space_uuid',
+                    space: localSpace,
+                    metaspace,
+                });
+                iReckon(lc, indexIbGib.data?.mySpaceId).willEqual('local_space_uuid');
+                iReckon(lc, indexIbGib.data?.staged_item).willEqual([]);
+                iReckon(lc, indexIbGib.rel8ns?.staged_item).isGonnaBeFalsy();
+            }
+            finally {
+                await fs.rm(testDir, { recursive: true, force: true });
+            }
+        });
+    });
+});
+//# sourceMappingURL=vcs-gib.respec.node.mjs.map

package/dist/vcs-gib.respec.node.mjs.map

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

package/generate-version-file.js

@@ -0,0 +1,20 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const packageJsonPath = path.join(__dirname, 'package.json');
+const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+const versionContent = `/**
+ * @module AUTO-GENERATED-version
+ * Auto-generated version constant. Do NOT edit directly.
+ */
+export const AUTO_GENERATED_VERSION = '${pkg.version}';
+`;
+
+const outputPath = path.join(__dirname, 'src', 'AUTO-GENERATED-version.mts');
+fs.writeFileSync(outputPath, versionContent, 'utf8');
+console.log(`[generate-version-file] Updated ${outputPath} to version ${pkg.version}`);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ibgib/vcs-gib",
+  "version": "0.0.6",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ibgib": "dist/cli/vcs-cli-main.mjs",
+    "vcs": "dist/cli/vcs-cli-main.mjs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node dist/respec-gib.node.mjs",
+    "test:node:nobuild": "node dist/respec-gib.node.mjs",
+    "generate-version": "node generate-version-file.js",
+    "build:for:test": "node tools/pack-for-test.mjs",
+    "pack": "npm pack --pack-destination=\"./published\"",
+    "prepare:publish": "npm version patch && node ../../build/dist/concrete-build/build-vcs-gib.mjs --prod && npm run pack"
+  },
+  "dependencies": {
+    "@ibgib/helper-gib": "^0.0.36",
+    "@ibgib/ts-gib": "^0.5.33",
+    "@ibgib/encrypt-gib": "^0.2.37",
+    "@ibgib/core-gib": "^0.1.69",
+    "@ibgib/node-gib": "^0.0.13"
+  }
+}

package/src/AUTO-GENERATED-version.mts

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

package/src/assumptions.respec.mts

@@ -0,0 +1,50 @@
+import {
+    ifWe, iReckon, respecfully
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.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',
+}: {
+    s: string,
+    algorithm?: string,
+}): Promise<string> {
+    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: IbGib_V1 = { 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');
+    });
+
+});

package/src/bootstrap/node-bootstrap.mts

@@ -0,0 +1,198 @@
+/**
+ * @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 { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.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;
+
+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 async function bootstrapVcsMetaspace(
+    opts: BootstrapVcsMetaspaceOpts = {}
+): Promise<BootstrapVcsMetaspaceResult> {
+    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: string | undefined;
+        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: string | undefined;
+        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: any) {
+        console.error(`${lc} ${error?.message || error} (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete. (I: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a)`); }
+    }
+}

package/src/bootstrap/node-bootstrap.respec.node.mts

@@ -0,0 +1,35 @@
+/**
+ * @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 });
+        }
+    });
+});

package/src/cli/cli-arg-parser.mts

@@ -0,0 +1,119 @@
+/**
+ * @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 { RCLIParamInfo } from '@ibgib/helper-gib/dist/rcli/rcli-types.mjs';
+import {
+    VCS_SUBCOMMANDS,
+    VCS_PARAM_MESSAGE,
+    VCS_PARAM_BRANCH,
+    VCS_PARAM_ALL,
+    VCS_PARAM_FORCE,
+    VCS_PARAM_VERBOSE,
+    VCS_PARAM_HELP,
+    VCS_PARAM_SHARE_IGNORED,
+} 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[];
+}
+
+function matchesParam(arg: string, paramInfo: RCLIParamInfo): boolean {
+    if (!arg || !arg.startsWith('-')) {
+        return false;
+    }
+    const stripped = arg.replace(/^-+/, '');
+    if (paramInfo.name && stripped === paramInfo.name) {
+        return true;
+    }
+    if (paramInfo.synonyms && paramInfo.synonyms.includes(stripped)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Parses raw command line argument vector (process.argv.slice(2)).
+ */
+export function parseVcsArgs(argv: string[]): ParsedVcsArgs {
+    const rawArgs = [...argv];
+    let command: VcsSubcommand = VCS_SUBCOMMANDS.HELP;
+    const positionals: string[] = [];
+    const flags: ParsedVcsArgs['flags'] = {};
+
+    const validSubcommands = Object.values(VCS_SUBCOMMANDS) as string[];
+
+    let i = 0;
+    while (i < rawArgs.length) {
+        const arg = rawArgs[i];
+
+        if (matchesParam(arg, VCS_PARAM_HELP)) {
+            flags.help = true;
+            i++;
+        } else if (arg === '--version' || (arg === '-v' && rawArgs.length === 1)) {
+            if (command === VCS_SUBCOMMANDS.HELP) {
+                command = VCS_SUBCOMMANDS.VERSION;
+            }
+            i++;
+        } else if (matchesParam(arg, VCS_PARAM_MESSAGE)) {
+            flags.message = rawArgs[i + 1] || '';
+            i += 2;
+        } else if (matchesParam(arg, VCS_PARAM_BRANCH)) {
+            flags.branchName = rawArgs[i + 1] || '';
+            i += 2;
+        } else if (matchesParam(arg, VCS_PARAM_ALL)) {
+            flags.all = true;
+            i++;
+        } else if (matchesParam(arg, VCS_PARAM_FORCE)) {
+            flags.force = true;
+            i++;
+        } else if (matchesParam(arg, VCS_PARAM_VERBOSE)) {
+            flags.verbose = true;
+            i++;
+        } else if (matchesParam(arg, VCS_PARAM_SHARE_IGNORED)) {
+            flags.shareIgnored = true;
+            i++;
+        } else if (!arg.startsWith('-')) {
+            if (command === VCS_SUBCOMMANDS.HELP) {
+                const normalized = arg.toLowerCase();
+                if (validSubcommands.includes(normalized)) {
+                    command = normalized as VcsSubcommand;
+                } else {
+                    positionals.push(arg);
+                }
+            } else {
+                positionals.push(arg);
+            }
+            i++;
+        } else {
+            i++;
+        }
+    }
+
+    if (flags.help && command !== VCS_SUBCOMMANDS.VERSION) {
+        command = VCS_SUBCOMMANDS.HELP;
+    }
+
+    return {
+        command,
+        positionals,
+        flags,
+        rawArgs,
+    };
+}

package/src/cli/cli-arg-parser.respec.node.mts

@@ -0,0 +1,45 @@
+/**
+ * @module cli-arg-parser.respec
+ * 
+ * Unit tests for zero-dependency vcs CLI argument parser.
+ */
+
+import {
+    respecfully, ifWe, iReckon
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { parseVcsArgs } from './cli-arg-parser.mjs';
+
+const lc = `[apps/vcs-gib/src/cli/cli-arg-parser.respec.node.mts]`;
+
+await respecfully(lc, `Zero-Dependency CLI Argument Parser`, async () => {
+
+    await respecfully(lc, `parseVcsArgs`, async () => {
+        await ifWe(lc, `parses init command and target path positional`, async () => {
+            const parsed = parseVcsArgs(['init', 'my_repo']);
+            iReckon(lc, parsed.command).willEqual('init');
+            iReckon(lc, parsed.positionals[0]).willEqual('my_repo');
+        });
+
+        await ifWe(lc, `parses commit command with message flag -m`, async () => {
+            const parsed = parseVcsArgs(['commit', '-m', 'initial commit']);
+            iReckon(lc, parsed.command).willEqual('commit');
+            iReckon(lc, parsed.flags.message).willEqual('initial commit');
+        });
+
+        await ifWe(lc, `parses add command with --all flag and positionals`, async () => {
+            const parsed = parseVcsArgs(['add', 'src/index.mts', '--all']);
+            iReckon(lc, parsed.command).willEqual('add');
+            iReckon(lc, parsed.positionals[0]).willEqual('src/index.mts');
+            iReckon(lc, parsed.flags.all).isGonnaBeTrue();
+        });
+
+        await ifWe(lc, `defaults to help command when no args or --help specified`, async () => {
+            const parsed1 = parseVcsArgs([]);
+            iReckon(lc, parsed1.command).willEqual('help');
+
+            const parsed2 = parseVcsArgs(['status', '--help']);
+            iReckon(lc, parsed2.command).willEqual('help');
+        });
+    });
+});

package/src/cli/cli-constants.mts

@@ -0,0 +1,77 @@
+/**
+ * @module cli-constants
+ * 
+ * Constants and RCLIParamInfo parameter definitions for vcs CLI commands.
+ */
+
+import { RCLIParamInfo } from '@ibgib/helper-gib/dist/rcli/rcli-types.mjs';
+
+export const VCS_CMD_NAME = 'vcs';
+
+export const VCS_SUBCOMMANDS = {
+    INIT: 'init',
+    STATUS: 'status',
+    ADD: 'add',
+    COMMIT: 'commit',
+    LOG: 'log',
+    BRANCH: 'branch',
+    CHECKOUT: 'checkout',
+    HELP: 'help',
+    VERSION: 'version',
+} as const;
+
+export const VCS_PARAM_MESSAGE: RCLIParamInfo = {
+    name: 'message',
+    synonyms: ['m'],
+    description: 'Commit message description',
+    isFlag: false,
+    argTypeName: 'string',
+};
+
+export const VCS_PARAM_BRANCH: RCLIParamInfo = {
+    name: 'branch',
+    synonyms: ['b'],
+    description: 'Target branch name',
+    isFlag: false,
+    argTypeName: 'string',
+};
+
+export const VCS_PARAM_ALL: RCLIParamInfo = {
+    name: 'all',
+    synonyms: ['a'],
+    description: 'Stage all tracked and untracked files',
+    isFlag: true,
+    argTypeName: 'boolean',
+};
+
+export const VCS_PARAM_FORCE: RCLIParamInfo = {
+    name: 'force',
+    synonyms: ['f'],
+    description: 'Force operation execution',
+    isFlag: true,
+    argTypeName: 'boolean',
+};
+
+export const VCS_PARAM_VERBOSE: RCLIParamInfo = {
+    name: 'verbose',
+    synonyms: ['v'],
+    description: 'Enable detailed verbose console logging',
+    isFlag: true,
+    argTypeName: 'boolean',
+};
+
+export const VCS_PARAM_HELP: RCLIParamInfo = {
+    name: 'help',
+    synonyms: ['h'],
+    description: 'Display CLI help information',
+    isFlag: true,
+    argTypeName: 'boolean',
+};
+
+export const VCS_PARAM_SHARE_IGNORED: RCLIParamInfo = {
+    name: 'share-ignored',
+    synonyms: ['link-ignored'],
+    description: 'Share/symlink ignored directories across branch worktrees',
+    isFlag: true,
+    argTypeName: 'boolean',
+};