engineering-memory 1.10.3 → 1.10.5

package/dispatcher/sections.mjs

@@ -23,7 +23,9 @@ Do not edit until the skill lifecycle has completed discovery, its checkpoint, a
 
 Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. For a required decision, use \`questionnaire.ask\` to open a durable native MCP form and \`questionnaire.resume\` to return to the same unanswered question. Read the skill's questionnaires reference first. Never use request_user_input_async for a required decision: it does not wait for an answer. When the durable form is unavailable, use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. A timeout, dismissed form, empty response or ended turn is not an answer. Keep the decision pending and resume it; do not start dependent work or report it as resolved. Existing answers remain valid through retries and handoffs.
 
-When the repository is unbound, use the native questionnaire required by the skill. Do not silently create or bind a project. Do not open a survey web page.`;
+When the repository is unbound, use the native questionnaire required by the skill. Do not silently create or bind a project. Do not open a survey web page.
+
+For project creation or adoption, read the skill's project-onboarding reference. Use read-only maturity evidence, then native selection of greenfield, exhaustive adoption or phased rework. A missing folder or Git repository uses preparation:true questionnaires before project.initialize. Recognize later memory-refresh intent semantically and confirm its scope natively; never trigger it from a fixed word list. Adoption and refresh cover architecture, state, services, network, data, screens and cross-module flows, not just page logic.`;
 
 export const dispatcherSections = Object.freeze({
   codex: `${shared}\n\nInvoke the installed skill as \`$engineering-memory\` when an explicit skill invocation is needed.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "1.10.3",
+  "version": "1.10.5",
   "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/dist/src/git/source-snapshot.js

@@ -0,0 +1,450 @@
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { canonicalPath } from '../utilities/files.js';
+import { NativeCommandRunner } from '../utilities/process.js';
+export class SourceSnapshot {
+    runner;
+    constructor(runner = new NativeCommandRunner()) {
+        this.runner = runner;
+    }
+    async snapshot(repoRoot, ref = 'HEAD') {
+        const root = await canonicalPath(repoRoot);
+        const commit = await this.resolveCommit(root, ref);
+        const tree = await this.git(root, ['rev-parse', `${commit}^{tree}`]);
+        assertObjectId(tree, 'Git tree');
+        const output = await this.gitRaw(root, ['ls-tree', '-r', '-z', '--full-tree', commit, '--']);
+        const binaryPaths = await this.binaryPaths(root, commit);
+        const entries = parseTree(output);
+        const generatedRoots = await this.generatedRoots(root, entries);
+        const files = [];
+        for (const entry of entries) {
+            const binary = entry.type === 'blob' && binaryPaths.has(entry.path);
+            files.push(classify(entry, binary, generatedRoots));
+        }
+        files.sort(pathOrder);
+        return {
+            commit,
+            treeHash: tree,
+            manifestHash: sha256(stableStringify(files)),
+            files,
+        };
+    }
+    async read(repoRoot, commit, path, maxBytes = 1024 * 1024) {
+        const root = await canonicalPath(repoRoot);
+        assertCommit(commit);
+        const safePath = normalizePath(path);
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 16 * 1024 * 1024) {
+            throw new Error('Source read bound must be between 1 byte and 16 MiB');
+        }
+        const entry = await this.entry(root, commit, safePath);
+        if (!entry)
+            throw new Error(`Source path does not exist in ${commit}: ${safePath}`);
+        const classified = classify(entry, false);
+        if (classified.excludedReason)
+            throw new Error(`Source path is excluded: ${classified.excludedReason}`);
+        if (entry.type !== 'blob' || entry.mode === '120000' || entry.mode === '160000') {
+            throw new Error(`Source path is not a regular source blob: ${safePath}`);
+        }
+        const entries = [];
+        const segments = safePath.split('/');
+        for (let depth = 0; depth < segments.length; depth += 1) {
+            const prefix = segments.slice(0, depth).join('/');
+            const tree = prefix ? `${commit}:${prefix}` : commit;
+            const siblings = parseTree(await this.gitRaw(root, ['ls-tree', '-z', tree]));
+            for (const sibling of siblings) {
+                if (/^tsconfig(?:\.[^/]+)?\.json$/.test(sibling.path))
+                    entries.push({ ...sibling, path: prefix ? `${prefix}/${sibling.path}` : sibling.path });
+            }
+        }
+        const binaryClassified = classify(entry, (await this.binaryPaths(root, commit, safePath)).has(safePath), await this.generatedRoots(root, entries));
+        if (binaryClassified.excludedReason)
+            throw new Error(`Source path is excluded: ${binaryClassified.excludedReason}`);
+        const size = await this.blobSize(root, `${commit}:${safePath}`);
+        if (size > maxBytes)
+            throw new Error(`Source path exceeds the ${maxBytes}-byte read bound`);
+        const data = await this.gitBuffer(root, ['cat-file', 'blob', `${commit}:${safePath}`]);
+        if (data.includes(0))
+            throw new Error(`Source path is binary: ${safePath}`);
+        return data.toString('utf8');
+    }
+    compare(previous, current) {
+        const before = new Map(previous.files.map((file) => [file.path, file]));
+        const after = new Map(current.files.map((file) => [file.path, file]));
+        const added = [...after.keys()].filter((path) => !before.has(path));
+        const deleted = [...before.keys()].filter((path) => !after.has(path));
+        const unchanged = [...after.keys()].filter((path) => before.get(path)?.blobHash === after.get(path)?.blobHash);
+        const changed = [...after.keys()].filter((path) => before.has(path) && before.get(path).blobHash !== after.get(path).blobHash);
+        const oldByHash = uniqueHashMap(deleted.map((path) => before.get(path)));
+        const newByHash = uniqueHashMap(added.map((path) => after.get(path)));
+        const renamed = [...oldByHash.keys()]
+            .filter((hash) => newByHash.has(hash))
+            .map((blobHash) => ({
+            from: oldByHash.get(blobHash).path,
+            to: newByHash.get(blobHash).path,
+            blobHash,
+        }))
+            .sort((left, right) => left.from.localeCompare(right.from));
+        const renamedFrom = new Set(renamed.map((item) => item.from));
+        const renamedTo = new Set(renamed.map((item) => item.to));
+        const actualAdded = added.filter((path) => !renamedTo.has(path));
+        const actualDeleted = deleted.filter((path) => !renamedFrom.has(path));
+        return {
+            changedPaths: [
+                ...new Set([
+                    ...changed,
+                    ...actualAdded,
+                    ...actualDeleted,
+                    ...renamed.map((item) => item.to),
+                    ...renamed.map((item) => item.from),
+                ]),
+            ].sort(),
+            added: actualAdded.sort(),
+            deleted: actualDeleted.sort(),
+            renamed,
+            unchanged: unchanged.sort(),
+        };
+    }
+    async history(repoRoot, previousCommit, currentCommit = 'HEAD') {
+        const root = await canonicalPath(repoRoot);
+        assertRef(previousCommit);
+        const current = await this.resolveCommit(root, currentCommit);
+        let previous;
+        try {
+            previous = await this.resolveCommit(root, previousCommit);
+        }
+        catch {
+            return {
+                previousCommit,
+                currentCommit: current,
+                changes: emptyComparison(),
+                recentRelevantCommitIds: [],
+                fallback: 'missing-commit',
+            };
+        }
+        const before = await this.snapshot(root, previous);
+        const after = await this.snapshot(root, current);
+        const changes = this.compare(before, after);
+        const ancestry = await this.runner.run('git', ['merge-base', '--is-ancestor', previous, current], { cwd: root });
+        const shallow = await this.git(root, ['rev-parse', '--is-shallow-repository']);
+        if (ancestry.exitCode !== 0 && ancestry.exitCode !== 1)
+            throw new Error('Git ancestry lookup failed');
+        const fallback = shallow === 'true'
+            ? 'shallow-history'
+            : ancestry.exitCode === 1
+                ? 'unrelated-ancestry'
+                : undefined;
+        const relevant = await this.relevantCommitIds(root, previous, current, changes);
+        return {
+            previousCommit: previous,
+            currentCommit: current,
+            changes,
+            recentRelevantCommitIds: relevant.commitIds,
+            historyTruncated: relevant.truncated,
+            ...(fallback === undefined && !relevant.truncated
+                ? {}
+                : { fallback: fallback ?? 'history-truncated' }),
+        };
+    }
+    async entry(root, commit, path) {
+        const output = await this.gitRaw(root, [
+            '--literal-pathspecs',
+            'ls-tree',
+            '-z',
+            commit,
+            '--',
+            path,
+        ]);
+        const entries = parseTree(output);
+        return entries.length === 1 && entries[0].path === path ? entries[0] : null;
+    }
+    async resolveCommit(root, ref) {
+        assertRef(ref);
+        const commit = await this.git(root, [
+            'rev-parse',
+            '--verify',
+            '--end-of-options',
+            `${ref}^{commit}`,
+        ]);
+        assertCommit(commit);
+        return commit;
+    }
+    async git(root, args, input) {
+        const result = await this.runner.run('git', args, { cwd: root, input });
+        if (result.exitCode !== 0)
+            throw new Error(`Git command failed: ${result.stderr.trim() || args[0]}`);
+        return result.stdout.trim();
+    }
+    async gitRaw(root, args, input) {
+        const result = await this.runner.run('git', args, { cwd: root, input });
+        if (result.exitCode !== 0)
+            throw new Error(`Git command failed: ${result.stderr.trim() || args[0]}`);
+        return result.stdout;
+    }
+    async gitBuffer(root, args) {
+        const result = await this.runner.run('git', args, { cwd: root });
+        if (result.exitCode !== 0)
+            throw new Error(`Git object read failed: ${result.stderr.trim() || args[0]}`);
+        return Buffer.from(result.stdout, 'utf8');
+    }
+    async blobSize(root, object) {
+        const result = await this.runner.run('git', ['cat-file', '--batch-check=%(objecttype) %(objectsize)'], {
+            cwd: root,
+            input: `${object}\n`,
+        });
+        const match = /^(blob|tree|commit|tag) (\d+)$/.exec(result.stdout.trim());
+        if (result.exitCode !== 0 || !match || match[1] !== 'blob')
+            throw new Error(`Git object size lookup failed: ${result.stderr.trim() || object}`);
+        return Number(match[2]);
+    }
+    async binaryPaths(root, commit, path) {
+        const emptyTree = await this.git(root, ['hash-object', '-t', 'tree', '--stdin'], '');
+        assertObjectId(emptyTree, 'Git empty tree');
+        const output = await this.gitRaw(root, [
+            '--literal-pathspecs',
+            'diff',
+            '--numstat',
+            '-z',
+            '--no-renames',
+            '--no-ext-diff',
+            '--no-textconv',
+            emptyTree,
+            commit,
+            '--',
+            ...(path ? [path] : []),
+        ]);
+        const binary = new Set();
+        for (const record of output.split('\0').filter((value) => value.length > 0)) {
+            const match = /^-\t-\t(.*)$/.exec(record);
+            if (match)
+                binary.add(normalizePath(match[1]));
+        }
+        return binary;
+    }
+    async relevantCommitIds(root, previous, current, changes) {
+        const paths = [...new Set(changes.changedPaths)];
+        if (paths.length === 0)
+            return { commitIds: [], truncated: false };
+        const candidateIds = [];
+        const seen = new Set();
+        let truncated = false;
+        for (const chunk of pathspecChunks(paths)) {
+            const output = await this.gitRaw(root, [
+                '--literal-pathspecs',
+                'rev-list',
+                '--full-history',
+                '--topo-order',
+                '--max-count=21',
+                `${previous}..${current}`,
+                '--',
+                ...chunk,
+            ]);
+            const commits = output
+                .split(/\r?\n/)
+                .map((value) => value.trim())
+                .filter(Boolean);
+            if (commits.length === 21)
+                truncated = true;
+            for (const commit of commits) {
+                assertCommit(commit);
+                if (!seen.has(commit)) {
+                    seen.add(commit);
+                    candidateIds.push(commit);
+                }
+            }
+        }
+        if (candidateIds.length <= 20)
+            return { commitIds: candidateIds, truncated };
+        const orderedOutput = await this.gitRaw(root, ['rev-list', '--topo-order', '--no-walk=sorted', '--stdin'], `${candidateIds.join('\n')}\n`);
+        const ordered = orderedOutput
+            .split(/\r?\n/)
+            .map((value) => value.trim())
+            .filter(Boolean);
+        for (const commit of ordered)
+            assertCommit(commit);
+        return { commitIds: ordered.slice(0, 20), truncated: true };
+    }
+    async generatedRoots(root, entries) {
+        const roots = new Set();
+        const configs = entries.filter((entry) => entry.type === 'blob' &&
+            /^100(?:644|755)$/.test(entry.mode) &&
+            /(^|\/)tsconfig(?:\.[^/]+)?\.json$/.test(entry.path) &&
+            !classify(entry).excludedReason);
+        for (const config of configs) {
+            if ((await this.blobSize(root, config.blobHash)) > 64 * 1024)
+                continue;
+            const text = await this.gitRaw(root, ['cat-file', 'blob', config.blobHash]);
+            let value;
+            try {
+                value = JSON.parse(text);
+            }
+            catch {
+                continue;
+            }
+            if (!isRecord(value) || !isRecord(value.compilerOptions))
+                continue;
+            const directory = config.path.slice(0, config.path.lastIndexOf('/') + 1);
+            for (const output of [value.compilerOptions.outDir, value.compilerOptions.declarationDir]) {
+                if (typeof output !== 'string')
+                    continue;
+                const normalized = output.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+                if (!normalized ||
+                    normalized.startsWith('/') ||
+                    /[:\0\r\n]/.test(normalized) ||
+                    normalized.split('/').some((part) => !part || part === '.' || part === '..'))
+                    continue;
+                roots.add(`${directory}${normalized}/`);
+            }
+        }
+        return roots;
+    }
+}
+function parseTree(output) {
+    return output
+        .split('\0')
+        .filter(Boolean)
+        .map((token) => {
+        const match = /^(\d{6}) (\w+) ([0-9a-f]{40,64})\t(.+)$/.exec(token);
+        if (!match)
+            throw new Error('Git returned an invalid tree entry');
+        return {
+            mode: match[1],
+            type: match[2],
+            blobHash: match[3],
+            path: normalizePath(match[4]),
+        };
+    });
+}
+function normalizePath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    if (!normalized ||
+        normalized.startsWith('/') ||
+        /^[A-Za-z]:\//.test(normalized) ||
+        normalized.split('/').includes('..') ||
+        normalized.includes('\0')) {
+        throw new Error(`Git path is unsafe: ${path}`);
+    }
+    return normalized;
+}
+function assertCommit(commit) {
+    if (!/^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(commit))
+        throw new Error('Git commit must be a 40- or 64-hex object ID');
+}
+function classify(entry, binary = false, generatedRoots = new Set()) {
+    if (entry.mode === '120000' || entry.type === 'symlink')
+        return {
+            path: entry.path,
+            blobHash: entry.blobHash,
+            category: 'symlink',
+            excludedReason: 'symbolic link is not source text',
+        };
+    if (binary)
+        return {
+            path: entry.path,
+            blobHash: entry.blobHash,
+            category: 'binary',
+            excludedReason: 'binary content is not source text',
+        };
+    const path = entry.path.toLowerCase();
+    if (entry.mode === '160000' || entry.type === 'commit')
+        return {
+            path: entry.path,
+            blobHash: entry.blobHash,
+            category: 'submodule',
+            excludedReason: 'submodule entry is not source text',
+        };
+    if (/(^|\/)(node_modules|vendor|pods)(\/|$)/.test(path))
+        return {
+            ...entryFile(entry),
+            category: 'vendor',
+            excludedReason: 'third-party dependency directory',
+        };
+    if (/(^|\/)(\.git|\.dart_tool|\.next|\.nuxt)(\/|$)|\.(g|freezed)\.dart$|\.(?:[cm]?js|css)\.map$|\.(tsbuildinfo|class|pyc)$/.test(path) ||
+        [...generatedRoots].some((root) => entry.path.startsWith(root)))
+        return {
+            ...entryFile(entry),
+            category: 'generated',
+            excludedReason: 'generated or build output',
+        };
+    if (isSecretPath(path))
+        return {
+            ...entryFile(entry),
+            category: 'secret',
+            excludedReason: 'credential or private key material',
+        };
+    if (/(^|\/)(__tests__|test|tests|spec)(\/|$)|\.(test|spec)\.[^/]+$|(^|\/)[^/]+_test\.[^/]+$/.test(path))
+        return { ...entryFile(entry), category: 'test' };
+    if (/(^|\/)(assets?|public|static|res)(\/|$)|\.(png|jpe?g|gif|svg|webp|ico|mp3|mp4|wav|ttf|otf|woff2?)$/.test(path))
+        return { ...entryFile(entry), category: 'assets' };
+    if (/(^|\/)(docs?|documentation)(\/|$)|(^|\/)(readme|changelog|contributing)(\.|$)|\.md$/.test(path))
+        return { ...entryFile(entry), category: 'docs' };
+    if (/(^|\/)(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|pubspec\.yaml|pubspec\.lock|tsconfig[^/]*\.json|.*\.config\.[^/]+|\.gitignore|dockerfile|.*\.ya?ml|.*\.json)$/.test(path))
+        return { ...entryFile(entry), category: 'config' };
+    return { ...entryFile(entry), category: 'source' };
+}
+function entryFile(entry) {
+    return { path: entry.path, blobHash: entry.blobHash, category: 'source' };
+}
+function pathOrder(left, right) {
+    return Buffer.compare(Buffer.from(left.path, 'utf8'), Buffer.from(right.path, 'utf8'));
+}
+function assertObjectId(value, label) {
+    if (!/^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(value))
+        throw new Error(`${label} must be a 40- or 64-hex object ID`);
+}
+function uniqueHashMap(files) {
+    const result = new Map();
+    const duplicates = new Set();
+    for (const file of files) {
+        if (result.has(file.blobHash))
+            duplicates.add(file.blobHash);
+        else
+            result.set(file.blobHash, file);
+    }
+    for (const hash of duplicates)
+        result.delete(hash);
+    return result;
+}
+function isSecretPath(path) {
+    const segments = path.split('/');
+    const basename = segments.at(-1) ?? '';
+    const extension = basename.includes('.') ? basename.slice(basename.lastIndexOf('.')) : '';
+    if (/(^|\/)(\.env(?:\.[^/]*)?)(\/|$)/.test(path) ||
+        /\.(pem|key|p12|pfx|jks|keystore)$/.test(path) ||
+        /(^|\/)id_(rsa|dsa|ecdsa|ed25519)$/.test(path))
+        return true;
+    const exactSensitiveName = /^(?:secret|secrets|credential|credentials)(?:\.(json|ya?ml|toml|ini|conf|cfg|txt))?$/i.test(basename);
+    const sensitiveDirectory = segments
+        .slice(0, -1)
+        .some((segment) => /^(?:secret|secrets|credential|credentials)$/i.test(segment));
+    return (exactSensitiveName ||
+        (sensitiveDirectory && /\.(json|ya?ml|toml|ini|conf|cfg|txt)$/i.test(extension)));
+}
+function emptyComparison() {
+    return { changedPaths: [], added: [], deleted: [], renamed: [], unchanged: [] };
+}
+function assertRef(ref) {
+    if (!ref || ref.length > 256 || ref.startsWith('-') || !/^[A-Za-z0-9._/@-]+$/.test(ref))
+        throw new Error('Git ref is invalid');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const MAX_PATHSPEC_ARGUMENT_BYTES = 12 * 1024;
+function pathspecChunks(paths) {
+    const chunks = [];
+    let current = [];
+    let bytes = 0;
+    for (const path of paths) {
+        const pathBytes = Buffer.byteLength(path, 'utf8') + 1;
+        if (current.length > 0 && bytes + pathBytes > MAX_PATHSPEC_ARGUMENT_BYTES) {
+            chunks.push(current);
+            current = [];
+            bytes = 0;
+        }
+        current.push(path);
+        bytes += pathBytes;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+//# sourceMappingURL=source-snapshot.js.map

package/runtime/dist/src/index.js

@@ -17,6 +17,7 @@ import { RepositoryDecisionStore } from './runtime/repository-decision-store.js'
 import { ShadowNoticeStore } from './runtime/shadow-notice-store.js';
 import { UpdateChoiceStore } from './runtime/update-choice-store.js';
 import { PrincipalStateGuard } from './runtime/principal-state.js';
+import { OnboardingStore } from './runtime/onboarding-store.js';
 import { QuestionnaireStore } from './runtime/questionnaire-store.js';
 export function createBridgeService() {
     const config = loadBridgeConfig();
@@ -61,6 +62,7 @@ export function createBridgeService() {
         updateChoices,
         shadowNotices,
         questionnaires: new QuestionnaireStore(stateRoot),
+        onboarding: new OnboardingStore(stateRoot),
         clientVersion: config.clientVersion,
         principalState,
     });