@deploybuddy/node-adapter 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeployBuddy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @deploybuddy/node-adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only Node.js filesystem and Git evidence collection for DeployBuddy. Git is invoked through argument arrays with bounded execution; the adapter does not mutate repository state.
+
+```ts
+import { NodeWorkspaceAdapter } from '@deploybuddy/node-adapter';
+
+const adapter = new NodeWorkspaceAdapter(process.cwd());
+const git = await adapter.getGitSignals();
+```
+
+Build with `npm run build`. See the monorepo [architecture and compatibility policy](../../docs/architecture.md).

package/dist/NodeWorkspaceAdapter.d.ts

@@ -0,0 +1,28 @@
+import { type ChangedFile, type CheckResult, type ConfigParseResult, type ContextSignals, type DiagnosticSignals, type GitSignals, type PolicyParseResult, type ProjectMarker, type ProjectProfile, type TestSignals, type WorkspaceAdapter } from '@deploybuddy/core';
+export declare class NodeWorkspaceAdapter implements WorkspaceAdapter {
+    readonly cwd: string;
+    private markersPromise?;
+    private configTextPromise?;
+    private workingChangedFiles?;
+    constructor(cwd?: string);
+    beginCollection(): void;
+    getWorkspaceFolders(): Promise<string[]>;
+    getDiagnostics(): Promise<DiagnosticSignals>;
+    getTestSignals(): Promise<TestSignals>;
+    getContext(): Promise<ContextSignals>;
+    getGitSignals(): Promise<GitSignals>;
+    getChangedFiles(range?: {
+        from: string;
+        to: string;
+    } | {
+        base: string;
+    }): Promise<ChangedFile[]>;
+    private resolveRevision;
+    getProjectProfile(): Promise<ProjectProfile>;
+    getCheckResults(): Promise<CheckResult[]>;
+    getConfig(): Promise<ConfigParseResult>;
+    getPolicy(): Promise<PolicyParseResult>;
+    private getConfigText;
+    getMarkers(): Promise<ProjectMarker[]>;
+    private readMarkers;
+}

package/dist/NodeWorkspaceAdapter.js

@@ -0,0 +1,274 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeWorkspaceAdapter = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const core_1 = require("@deploybuddy/core");
+const execFile = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const GIT_TIMEOUT_MS = 10_000;
+const MAX_CONFIG_BYTES = 256 * 1024;
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const excluded = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.next', '.nuxt', 'target']);
+const unavailableGit = () => ({ available: false, repositories: [], branch: null, upstream: null, ahead: null, behind: null, modifiedFiles: 0, stagedFiles: 0, untrackedFiles: 0, changedFiles: 0, unstagedFiles: null, conflictFiles: null, detachedHead: null, hasUncommittedChanges: false, dirtyPrimaryBranch: false, note: 'Git is unavailable or this directory is not a Git repository.' });
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const keys = (value) => Object.keys(object(value));
+const stringMap = (value) => Object.fromEntries(Object.entries(object(value)).filter((entry) => typeof entry[1] === 'string'));
+class NodeWorkspaceAdapter {
+    cwd;
+    markersPromise;
+    configTextPromise;
+    workingChangedFiles;
+    constructor(cwd = process.cwd()) { this.cwd = node_path_1.default.resolve(cwd); }
+    beginCollection() { this.markersPromise = undefined; this.configTextPromise = undefined; this.workingChangedFiles = undefined; }
+    async getWorkspaceFolders() { return ['.']; }
+    async getDiagnostics() { return { available: false, errors: 0, warnings: 0, note: 'Node CLI has no language-server diagnostics. Use your project lint/build checks.' }; }
+    async getTestSignals() { return { testStatus: 'unknown', passed: null, failed: null, skipped: null, notRun: null, note: 'Test results have not been collected. Available test commands are listed by `deploybuddy checks`.' }; }
+    async getContext() {
+        const now = new Date();
+        return { day: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][now.getDay()] ?? 'Unknown', dayOfWeek: now.getDay(), hour: now.getHours(), minute: now.getMinutes(), timestamp: now.toISOString() };
+    }
+    async getGitSignals() {
+        try {
+            const { stdout } = await execFile('git', ['--no-optional-locks', 'status', '--porcelain=v1', '--branch', '--untracked-files=all', '-z'], { cwd: this.cwd, maxBuffer: 1024 * 1024, timeout: GIT_TIMEOUT_MS, windowsHide: true });
+            const entries = stdout.split('\0').filter(Boolean);
+            const header = entries.shift() ?? '';
+            const match = /^## (.*)$/.exec(header);
+            const branchText = match?.[1] ?? '';
+            const detached = /\(HEAD detached|HEAD \(no branch\)/i.test(branchText);
+            const aheadBehind = /\[(?:ahead (\d+))?(?:, )?(?:behind (\d+))?\]/.exec(branchText);
+            const upstreamMatch = /\.\.\.([^ ]+)/.exec(branchText);
+            const branch = detached ? null : branchText.replace(/\.\.\..*$/, '').replace(/ \[.*$/, '').replace(/^No commits yet on /, '') || null;
+            let revision;
+            try {
+                const [{ stdout: headOutput }, { stdout: branchOutput }] = await Promise.all([
+                    execFile('git', ['rev-parse', '--verify', 'HEAD'], { cwd: this.cwd, maxBuffer: 4096, timeout: GIT_TIMEOUT_MS, windowsHide: true }),
+                    execFile('git', ['branch', '--show-current'], { cwd: this.cwd, maxBuffer: 4096, timeout: GIT_TIMEOUT_MS, windowsHide: true }),
+                ]);
+                const sha = headOutput.trim().toLowerCase();
+                if (/^[a-f0-9]{40,64}$/.test(sha))
+                    revision = { sha, shortSha: sha.slice(0, 7), ...(branchOutput.trim() ? { branch: branchOutput.trim().slice(0, 255) } : {}), detached };
+            }
+            catch { /* Keep usable repository status when HEAD identity is unavailable. */ }
+            const upstream = upstreamMatch?.[1] ?? null;
+            const ahead = upstream ? Number(aheadBehind?.[1] ?? 0) : null;
+            const behind = upstream ? Number(aheadBehind?.[2] ?? 0) : null;
+            const changedPaths = new Set();
+            const fileChanges = [];
+            let stagedFiles = 0;
+            let unstagedFiles = 0;
+            let untrackedFiles = 0;
+            let conflictFiles = 0;
+            for (let i = 0; i < entries.length; i++) {
+                const item = entries[i] ?? '';
+                const xy = item.slice(0, 2);
+                const file = item.slice(3);
+                if (xy === '??') {
+                    untrackedFiles++;
+                    fileChanges.push({ path: file, status: 'added' });
+                }
+                else {
+                    changedPaths.add(file);
+                    fileChanges.push({ path: file, status: xy.includes('R') || xy.includes('C') ? 'renamed' : xy.includes('A') ? 'added' : xy.includes('D') ? 'deleted' : xy.trim() ? 'modified' : 'unknown' });
+                    if (xy[0] !== ' ')
+                        stagedFiles++;
+                    if (xy[1] !== ' ')
+                        unstagedFiles++;
+                    if (['UU', 'AA', 'DD', 'AU', 'UA', 'DU', 'UD'].includes(xy))
+                        conflictFiles++;
+                    if (xy.includes('R') || xy.includes('C'))
+                        i++;
+                }
+            }
+            this.workingChangedFiles = (0, core_1.normalizeChangedFiles)(fileChanges);
+            const changedFiles = changedPaths.size + untrackedFiles;
+            const hasUncommittedChanges = changedFiles > 0;
+            const repository = { root: '.', branch, upstream, ahead, behind, unstagedFiles, conflictFiles, detachedHead: detached, modifiedFiles: changedPaths.size, stagedFiles, untrackedFiles, changedFiles, hasUncommittedChanges, ...(revision ? { revision } : {}) };
+            return { available: true, repositories: [repository], branch, upstream, ahead, behind, unstagedFiles, conflictFiles, detachedHead: detached, modifiedFiles: repository.modifiedFiles, stagedFiles, untrackedFiles, changedFiles, hasUncommittedChanges, dirtyPrimaryBranch: hasUncommittedChanges && (branch === 'main' || branch === 'master'), ...(revision ? { revision } : {}) };
+        }
+        catch {
+            this.workingChangedFiles = [];
+            return unavailableGit();
+        }
+    }
+    async getChangedFiles(range) {
+        try {
+            if (range && 'from' in range) {
+                const from = await this.resolveRevision(range.from);
+                const to = await this.resolveRevision(range.to);
+                const { stdout } = await execFile('git', ['--no-optional-locks', 'diff', '--name-status', '-z', '--no-renames', `${from}...${to}`], { cwd: this.cwd, maxBuffer: 4 * 1024 * 1024, timeout: GIT_TIMEOUT_MS, windowsHide: true });
+                return parseNameStatus(stdout);
+            }
+            if (range && 'base' in range) {
+                const base = await this.resolveRevision(range.base);
+                const { stdout } = await execFile('git', ['--no-optional-locks', 'diff', '--name-status', '-z', '--no-renames', `${base}...HEAD`], { cwd: this.cwd, maxBuffer: 4 * 1024 * 1024, timeout: GIT_TIMEOUT_MS, windowsHide: true });
+                return parseNameStatus(stdout);
+            }
+            if (this.workingChangedFiles)
+                return this.workingChangedFiles;
+            const { stdout } = await execFile('git', ['--no-optional-locks', 'status', '--porcelain=v1', '-z', '--untracked-files=all'], { cwd: this.cwd, maxBuffer: 4 * 1024 * 1024, timeout: GIT_TIMEOUT_MS, windowsHide: true });
+            const parts = stdout.split('\0').filter(Boolean);
+            const files = [];
+            for (let i = 0; i < parts.length; i++) {
+                const record = parts[i] ?? '';
+                const status = record.slice(0, 2);
+                const filePath = record.slice(3);
+                if (status === '??')
+                    files.push({ path: filePath, status: 'added' });
+                else {
+                    const normalizedStatus = status.includes('R') || status.includes('C') ? 'renamed' : status.includes('A') ? 'added' : status.includes('D') ? 'deleted' : status.trim() ? 'modified' : 'unknown';
+                    files.push({ path: filePath, status: normalizedStatus });
+                    if (status.includes('R') || status.includes('C'))
+                        i++;
+                }
+            }
+            return (0, core_1.normalizeChangedFiles)(files);
+        }
+        catch (error) {
+            if (range)
+                throw new Error(`Could not inspect the requested Git change range. Check that the revision exists and is reachable locally.`, { cause: error });
+            return [];
+        }
+    }
+    async resolveRevision(revision) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,127}$/.test(revision) || revision.includes('..') || revision.includes('//') || revision.startsWith('-') || revision.endsWith('/') || revision.includes('@{'))
+            throw new Error('Invalid Git revision.');
+        const { stdout } = await execFile('git', ['--no-optional-locks', 'rev-parse', '--verify', `${revision}^{commit}`], { cwd: this.cwd, maxBuffer: 4096, timeout: GIT_TIMEOUT_MS, windowsHide: true });
+        const resolved = stdout.trim().toLowerCase();
+        if (!/^[a-f0-9]{40,64}$/.test(resolved))
+            throw new Error('Git revision could not be resolved.');
+        return resolved;
+    }
+    async getProjectProfile() { return (0, core_1.detectProjectProfile)(await this.getMarkers(), true); }
+    async getCheckResults() { return (0, core_1.detectChecks)(await this.getMarkers(), true); }
+    async getConfig() {
+        try {
+            return (0, core_1.parseDeployBuddyConfig)(await this.getConfigText());
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT')
+                return (0, core_1.parseDeployBuddyConfig)(undefined);
+            if (isNodeError(error) && error.code === 'EFBIG')
+                return (0, core_1.parseDeployBuddyConfig)(' '.repeat(MAX_CONFIG_BYTES + 1));
+            return (0, core_1.parseDeployBuddyConfig)('{');
+        }
+    }
+    async getPolicy() {
+        try {
+            return (0, core_1.parseDeployBuddyPolicy)(await this.getConfigText());
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT')
+                return (0, core_1.parseDeployBuddyPolicy)(undefined);
+            if (isNodeError(error) && error.code === 'EFBIG')
+                return (0, core_1.parseDeployBuddyPolicy)(' '.repeat(MAX_CONFIG_BYTES + 1));
+            return (0, core_1.parseDeployBuddyPolicy)('{');
+        }
+    }
+    getConfigText() { this.configTextPromise ??= readOptionalBoundedText(this.cwd, '.deploybuddy.json', MAX_CONFIG_BYTES); return this.configTextPromise; }
+    async getMarkers() {
+        this.markersPromise ??= this.readMarkers();
+        return this.markersPromise;
+    }
+    async readMarkers() {
+        const roots = [{ absolute: this.cwd, relative: './' }];
+        try {
+            const entries = await (0, promises_1.readdir)(this.cwd, { withFileTypes: true });
+            for (const entry of entries)
+                if (entry.isDirectory() && !entry.name.startsWith('.') && !excluded.has(entry.name))
+                    roots.push({ absolute: node_path_1.default.join(this.cwd, entry.name), relative: `./${safeSegment(entry.name)}` });
+        }
+        catch {
+            return [];
+        }
+        const markers = [];
+        for (const root of roots) {
+            let files;
+            try {
+                files = await (0, promises_1.readdir)(root.absolute);
+            }
+            catch {
+                continue;
+            }
+            if (!files.includes('package.json') && !files.includes('composer.json') && !files.includes('artisan') && !files.some(name => /^vite\.config\./.test(name)))
+                continue;
+            const marker = { root: root.relative, files, packageManagerFiles: files.filter(name => /^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/.test(name)) };
+            if (files.includes('package.json')) {
+                try {
+                    const data = JSON.parse(await readBoundedText(root.absolute, 'package.json', MAX_MANIFEST_BYTES));
+                    const manifest = object(data);
+                    marker.packageDependencies = [...keys(manifest.dependencies), ...keys(manifest.devDependencies), ...keys(manifest.optionalDependencies)];
+                    marker.packageScripts = stringMap(manifest.scripts);
+                    marker.packageManager = typeof manifest.packageManager === 'string' ? manifest.packageManager : undefined;
+                }
+                catch {
+                    marker.parseErrors = [`Could not parse package.json in ${root.relative}`];
+                }
+            }
+            if (files.includes('composer.json')) {
+                try {
+                    const manifest = object(JSON.parse(await readBoundedText(root.absolute, 'composer.json', MAX_MANIFEST_BYTES)));
+                    marker.composerDependencies = [...keys(manifest.require), ...keys(manifest['require-dev'])];
+                    marker.composerScripts = stringMap(manifest.scripts);
+                }
+                catch {
+                    marker.parseErrors = [...(marker.parseErrors ?? []), `Could not parse composer.json in ${root.relative}`];
+                }
+            }
+            markers.push(marker);
+        }
+        return markers;
+    }
+}
+exports.NodeWorkspaceAdapter = NodeWorkspaceAdapter;
+function parseNameStatus(output) {
+    const parts = output.split('\0');
+    const files = [];
+    for (let i = 0; i < parts.length;) {
+        const code = parts[i++] ?? '';
+        if (!code)
+            continue;
+        const filePath = parts[i++] ?? '';
+        const status = code[0] === 'A' ? 'added' : code[0] === 'D' ? 'deleted' : code[0] === 'R' || code[0] === 'C' ? 'renamed' : code[0] === 'M' || code[0] === 'T' ? 'modified' : 'unknown';
+        files.push({ path: filePath, status });
+        if (code[0] === 'R' || code[0] === 'C')
+            i++;
+    }
+    return (0, core_1.normalizeChangedFiles)(files);
+}
+function isNodeError(error) { return error instanceof Error && 'code' in error; }
+function safeSegment(value) { return value.replace(/[^a-z0-9._ -]/gi, '_').slice(0, 64) || '_'; }
+async function readOptionalBoundedText(directory, name, limit) {
+    try {
+        return await readBoundedText(directory, name, limit);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function readBoundedText(directory, name, limit) {
+    const filename = node_path_1.default.join(directory, name);
+    const before = await (0, promises_1.lstat)(filename);
+    if (!before.isFile() || before.isSymbolicLink())
+        throw Object.assign(new Error('Expected a regular workspace file.'), { code: 'EINVAL' });
+    if (before.size > limit)
+        throw Object.assign(new Error('Workspace metadata file exceeds the size limit.'), { code: 'EFBIG' });
+    const noFollow = typeof node_fs_1.constants.O_NOFOLLOW === 'number' ? node_fs_1.constants.O_NOFOLLOW : 0;
+    const handle = await (0, promises_1.open)(filename, node_fs_1.constants.O_RDONLY | noFollow);
+    try {
+        const after = await handle.stat();
+        if (!after.isFile() || after.size > limit || before.dev !== after.dev || before.ino !== after.ino)
+            throw Object.assign(new Error('Workspace metadata file changed during inspection or exceeds the size limit.'), { code: 'EFBIG' });
+        return await handle.readFile({ encoding: 'utf8' });
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { NodeWorkspaceAdapter } from './NodeWorkspaceAdapter';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeWorkspaceAdapter = void 0;
+var NodeWorkspaceAdapter_1 = require("./NodeWorkspaceAdapter");
+Object.defineProperty(exports, "NodeWorkspaceAdapter", { enumerable: true, get: function () { return NodeWorkspaceAdapter_1.NodeWorkspaceAdapter; } });

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@deploybuddy/node-adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Read-only Node.js workspace inspection for DeployBuddy.",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prestone2/deploybuddy.git",
+    "directory": "packages/node-adapter"
+  },
+  "homepage": "https://github.com/prestone2/deploybuddy#readme",
+  "bugs": {
+    "url": "https://github.com/prestone2/deploybuddy/issues"
+  },
+  "keywords": [
+    "deployment",
+    "git",
+    "workspace",
+    "node"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.cjs"
+  },
+  "dependencies": {
+    "@deploybuddy/core": "file:../core"
+  }
+}