engineering-memory 0.1.0

package/runtime/dist/src/mcp/server.js

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { registerEngineeringMemoryTools } from './tool-definitions.js';
+export function createEngineeringMemoryServer(service) {
+    const server = new McpServer({
+        name: 'engineering-memory',
+        version: '0.1.0',
+    });
+    registerEngineeringMemoryTools(server, service);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/runtime/dist/src/mcp/tool-definitions.js

@@ -0,0 +1,405 @@
+import * as z from 'zod/v4';
+import { validationIds } from '../runtime/bridge-service.js';
+const optionalRepoRoot = z.string().min(1).optional();
+const stringList = z.array(z.string().min(1));
+const jsonValue = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValue),
+    z.record(z.string(), jsonValue),
+]));
+const jsonObject = z.record(z.string(), jsonValue);
+const stateDocument = z.object({
+    objective: z.string().optional(),
+    phase: z.string().optional(),
+    completed: stringList.optional(),
+    nextAction: z.string().optional(),
+    blockers: stringList.optional(),
+    forbiddenActions: stringList.optional(),
+});
+const handoffDocument = z.object({
+    completed: stringList.optional(),
+    remaining: stringList.optional(),
+    restartFrom: z.string().optional(),
+});
+const documents = z
+    .object({
+    state: stateDocument.optional(),
+    decisions: stringList.optional(),
+    discovery: stringList.optional(),
+    validation: stringList.optional(),
+    handoff: handoffDocument.optional(),
+})
+    .optional();
+const checkpointBase = {
+    repoRoot: optionalRepoRoot,
+    taskId: z.string().min(1),
+    projectId: z.string().min(1),
+    taskSlug: z.string().min(1),
+    summary: z.string().min(1),
+    details: z.string().optional(),
+    documents,
+    idempotencyKey: z.string().uuid().optional(),
+};
+export const engineeringMemoryToolNames = [
+    'session.bootstrap',
+    'session.resume',
+    'context.prepare_change',
+    'context.refresh',
+    'memory.query',
+    'memory.history',
+    'memory.propose_revision',
+    'memory.list_proposals',
+    'memory.review_proposal',
+    'task.checkpoint',
+    'task.record_correction',
+    'task.self_review',
+    'task.reconcile',
+    'task.resolve_pending_delivery',
+    'task.verify',
+    'task.close',
+    'architecture.plan',
+    'architecture.module',
+    'architecture.record_application',
+    'organization.list',
+    'organization.create',
+    'project.setup',
+    'project.list',
+    'project.resolve',
+    'project.member_add',
+    'auth.status',
+    'auth.signin_browser',
+    'auth.logout',
+];
+export function registerEngineeringMemoryTools(server, service) {
+    server.registerTool('session.bootstrap', {
+        description: 'Authenticate, resolve the repository project, open or resume a write or read-only task, and load mandatory engineering context before planning.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            projectId: z.string().optional(),
+            externalTaskId: z.string().min(2),
+            objective: z.string().min(2),
+            taskKind: z.string().min(2),
+            mode: z.enum(['write', 'read_only', 'scaffold']).optional(),
+            knownRevisions: z.record(z.string(), z.number().int().min(0)).optional(),
+        }),
+    }, async (input) => toolResult(await service.sessionBootstrap(input)));
+    server.registerTool('session.resume', {
+        description: 'Merge backend events, local journal, offline outbox, pinned context and current Git state after a new chat or context compaction.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            projectId: z.string().min(1).optional(),
+            taskSlug: z.string().min(1).optional(),
+            sessionId: z.string().min(1).optional(),
+            afterSequence: z.number().int().min(0).optional(),
+        }),
+    }, async (input) => toolResult(await service.sessionResume(input)));
+    server.registerTool('context.prepare_change', {
+        description: 'Load path-specific engineering memory, obtain a revision-pinned change lease, or explicitly transition a read-only task to write mode before editing.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            sessionId: z.string().min(1),
+            changedPaths: stringList.min(1),
+            transitionToWrite: z.boolean().optional(),
+        }),
+    }, async (input) => toolResult(await service.contextPrepareChange(input)));
+    server.registerTool('context.refresh', {
+        description: 'Invalidate stale revision pins after an approved memory change and require a new prepare-change lease.',
+        inputSchema: z.object({
+            sessionId: z.string().min(1),
+        }),
+    }, async (input) => toolResult(await service.contextRefresh(input)));
+    server.registerTool('memory.query', {
+        description: 'Read the smallest project memory pack needed for screens, components, services, navigation, localization or state work.',
+        inputSchema: z.object({
+            projectId: z.string().min(1),
+            sessionId: z.string().min(1),
+            kinds: stringList.optional(),
+            changedPaths: stringList.optional(),
+            codeSymbols: stringList.optional(),
+            figmaNodeIds: stringList.optional(),
+            tags: stringList.optional(),
+        }),
+    }, async (input) => toolResult(await service.memoryQuery(input)));
+    server.registerTool('memory.history', {
+        description: 'Read why the code you are about to change is the way it is: the revision history of the screen, component or contract records covering the given paths or keys, each revision with the task that produced it and the stated reason, plus the earlier tasks that touched those records and how many corrections each of them took. Also returns the task references found in the Git history of those paths. Verification refuses while a record with earlier work on it was never read.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            sessionId: z.string().min(1),
+            resourceKeys: z.array(z.string().min(1)).optional(),
+            paths: z.array(z.string().min(1)).optional(),
+            depth: z.number().int().min(1).max(50).optional(),
+        }),
+    }, async (input) => toolResult(await service.memoryHistory(input)));
+    server.registerTool('memory.propose_revision', {
+        description: 'Create an inactive, reviewable proposal for a permanent project or organization engineering memory revision.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            resourceId: z.string().optional(),
+            projectId: z.string().min(1),
+            taskId: z.string().optional(),
+            scope: z.enum(['product', 'organization', 'project']),
+            kind: z.enum([
+                'engineering_rule',
+                'project_profile',
+                'service_contract',
+                'localization_contract',
+                'navigation_contract',
+                'state_contract',
+                'screen_logic',
+                'component_mapping',
+                'figma_mapping',
+                'figma_reference',
+                'flow_logic',
+                'current_deviation',
+                'quality_gate',
+                'task_history',
+                'architecture_template',
+            ]),
+            resourceKey: z.string().min(2),
+            title: z.string().min(2),
+            baseRevision: z.number().int().min(0),
+            content: z.string().min(1),
+            reason: z.string().min(1),
+            affectedAreas: stringList,
+            regressionEvidence: jsonObject,
+            pathPatterns: stringList.optional(),
+            codeSymbols: stringList.optional(),
+            figmaNodeIds: stringList.optional(),
+            tags: stringList.optional(),
+            metadata: jsonObject.optional(),
+            provenance: jsonObject.optional(),
+        }),
+    }, async (input) => toolResult(await service.memoryProposeRevision(input)));
+    server.registerTool('memory.list_proposals', {
+        description: 'List the permanent memory proposals still waiting for review, so an authorized reviewer can find them without database access. Pass proposalId to read one proposal with its proposed content.',
+        inputSchema: z.object({
+            projectId: z.string().min(1),
+            proposalId: z.string().min(1).optional(),
+        }),
+    }, async (input) => toolResult(await service.memoryListProposals(input)));
+    server.registerTool('memory.review_proposal', {
+        description: 'Approve or reject a permanent memory proposal after the user explicitly selects its scope.',
+        inputSchema: z.object({
+            proposalId: z.string().min(1),
+            projectId: z.string().min(1),
+            decision: z.enum(['approved', 'rejected']),
+            note: z.string().min(1).optional(),
+        }),
+    }, async (input) => toolResult(await service.memoryReviewProposal(input)));
+    server.registerTool('task.checkpoint', {
+        description: 'Atomically update local task Markdown projections and synchronize an idempotent mandatory checkpoint.',
+        inputSchema: z.object({
+            ...checkpointBase,
+            checkpointType: z.enum([
+                'bootstrap',
+                'discovery',
+                'pre_edit',
+                'phase_transition',
+                'validation_before',
+                'validation_after',
+                'handoff_before',
+            ]),
+        }),
+    }, async (input) => toolResult(await service.taskCheckpoint(input)));
+    server.registerTool('task.record_correction', {
+        description: 'Record a user correction immediately, then ask the user in the same reply where it belongs. Omitting correctionScope, or sending "pending", leaves the scope decision open and blocks task.verify until it is answered. Send the answer with the same correctionRef.',
+        inputSchema: z.object({
+            ...checkpointBase,
+            correctionScope: z
+                .enum(['pending', 'task', 'project', 'organization', 'product_default'])
+                .optional(),
+            correctionRef: z.string().min(1).optional(),
+        }),
+    }, async (input) => toolResult(await service.taskRecordCorrection(input)));
+    server.registerTool('task.self_review', {
+        description: 'Record that the changed code was read back against the rules that govern it, naming the knowledge resources reviewed and every conflict found with how it was resolved. task.verify refuses until this exists for the current diff, so any further edit requires reviewing again.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            taskId: z.string().min(1),
+            reviewedResourceIds: z.array(z.string().min(1)),
+            findings: z.array(z.object({
+                path: z.string().min(1),
+                rule: z.string().min(1),
+                issue: z.string().min(8),
+                resolution: z.string().min(8),
+            })),
+        }),
+    }, async (input) => toolResult(await service.taskSelfReview(input)));
+    server.registerTool('task.reconcile', {
+        description: 'Reconcile each changed screen or component with an approved revision or an explicit no-semantic-memory-change reason.',
+        inputSchema: z
+            .object({
+            repoRoot: optionalRepoRoot,
+            taskId: z.string().min(1),
+            resourceId: z.string().min(1),
+            type: z.enum(['approved_revision', 'no_semantic_memory_change']),
+            proposalId: z.string().optional(),
+            revisionId: z.string().optional(),
+            reason: z.string().optional(),
+        })
+            .superRefine((value, context) => {
+            if (value.type === 'approved_revision' && (!value.proposalId || !value.revisionId)) {
+                context.addIssue({
+                    code: 'custom',
+                    message: 'Approved reconciliation requires proposalId and revisionId',
+                });
+            }
+            if (value.type === 'no_semantic_memory_change' &&
+                (!value.reason || value.reason.length < 8)) {
+                context.addIssue({
+                    code: 'custom',
+                    message: 'No-semantic-change reconciliation requires a reason of at least 8 characters',
+                });
+            }
+        }),
+    }, async (input) => toolResult(await service.taskReconcile(input)));
+    server.registerTool('task.resolve_pending_delivery', {
+        description: 'Inspect or explicitly discard any pending delivery; journal events can be rebased after a version conflict, while permanent proposals require refreshed revision comparison and native user approval.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            outboxId: z.string().regex(/^[0-9a-f]{64}$/),
+            action: z.enum(['inspect', 'rebase', 'discard']),
+            confirmedBaseRevision: z.number().int().min(0).optional(),
+            proposalRebaseApproved: z.boolean().optional(),
+            confirm: z.boolean().optional(),
+        }),
+    }, async (input) => toolResult(await service.taskResolvePendingDelivery(input)));
+    server.registerTool('task.verify', {
+        description: 'Verify a write task with its lease or a read-only task against its pinned Git baseline, mandatory checkpoints, structured validations and synchronized outbox.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            taskId: z.string().min(1),
+            sessionId: z.string().min(1),
+            leaseId: z.string().min(1).optional(),
+            changedPaths: stringList.min(1).optional(),
+            validations: z
+                .array(z.object({
+                validationId: z.enum(validationIds),
+                command: z.string().min(1),
+                passed: z.boolean(),
+                outputHash: z.string().regex(/^[0-9a-f]{64}$/),
+            }))
+                .min(1),
+            newResources: z
+                .array(z.object({
+                path: z.string().min(1),
+                kind: z.enum(['screen_logic', 'component_mapping']),
+                resourceKey: z.string().min(2),
+            }))
+                .optional(),
+        }),
+    }, async (input) => toolResult(await service.taskVerify(input)));
+    server.registerTool('task.close', {
+        description: 'Close a task only when backend verification still matches the current Git diff hash.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            taskId: z.string().min(1),
+        }),
+    }, async (input) => toolResult(await service.taskClose(input)));
+    server.registerTool('organization.create', {
+        description: 'Create an organization the user named, with the short identifier they typed. Offer this underneath the organizations they already belong to; never invent the identifier from the name.',
+        inputSchema: z.object({
+            name: z.string().min(2).max(120),
+            slug: z.string().min(2).max(120),
+        }),
+    }, async (input) => toolResult(await service.organizationCreate(input)));
+    server.registerTool('project.setup', {
+        description: 'Create a policy-ready backend project from the native questionnaire and local repository audit, then write its secret-free marker.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            organizationId: z.string().uuid(),
+            projectName: z.string().min(2),
+            projectSlug: z.string().min(2).optional(),
+            framework: z.string().optional(),
+            figmaConfig: jsonObject,
+            initialProjectProfile: z.object({
+                title: z.string().min(2),
+                content: z.string().min(2),
+                screenPathPatterns: z.array(z.string().min(1)).min(1),
+                componentPathPatterns: z.array(z.string().min(1)).min(1),
+                metadata: jsonObject,
+                provenance: jsonObject,
+            }),
+        }),
+    }, async (input) => toolResult(await service.projectSetup(input)));
+    server.registerTool('architecture.plan', {
+        description: 'List the organization architecture modules in apply order with their manifests, rename map, asset contract and tenant-specific points. Returns no file bodies.',
+        inputSchema: z.object({
+            projectId: z.string().uuid(),
+            sessionId: z.string().uuid(),
+            moduleKeys: z.array(z.string().min(1)).optional(),
+        }),
+    }, async (input) => toolResult(await service.architecturePlan(input)));
+    server.registerTool('architecture.module', {
+        description: 'Load one architecture module with its full file bodies so the agent can apply the rename map and write the files itself.',
+        inputSchema: z.object({
+            projectId: z.string().uuid(),
+            sessionId: z.string().uuid(),
+            moduleKey: z.string().min(1),
+        }),
+    }, async (input) => toolResult(await service.architectureModule(input)));
+    server.registerTool('architecture.record_application', {
+        description: 'Record that a scaffold task wrote one architecture module, hashing each written file after the rename so verification can exempt untouched scaffolded files.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            taskId: z.string().min(1),
+            projectId: z.string().uuid(),
+            templateResourceId: z.string().uuid(),
+            templateRevisionId: z.string().uuid(),
+            files: z
+                .array(z.object({
+                templatePath: z.string().min(1),
+                path: z.string().min(1),
+            }))
+                .min(1),
+        }),
+    }, async (input) => toolResult(await service.architectureRecordApplication(input)));
+    server.registerTool('organization.list', {
+        description: 'List the organizations the authenticated user belongs to so project setup can inherit an existing engineering core instead of silently creating an empty organization.',
+        inputSchema: z.object({}),
+    }, async () => toolResult(await service.organizationList()));
+    server.registerTool('project.list', {
+        description: 'List projects available to the authenticated user so the agent can present them through the native questionnaire UI.',
+        inputSchema: z.object({}),
+    }, async () => toolResult(await service.projectList()));
+    server.registerTool('project.resolve', {
+        description: 'Resolve the current repository fingerprint or bind an explicitly selected project, then write the secret-free marker only after backend authorization succeeds.',
+        inputSchema: z.object({
+            repoRoot: optionalRepoRoot,
+            bind: z.boolean().optional(),
+            projectId: z.string().uuid().optional(),
+        }),
+    }, async (input) => toolResult(await service.projectResolve(input)));
+    server.registerTool('project.member_add', {
+        description: 'Add an existing Engineering Memory account to a project with an explicit role.',
+        inputSchema: z.object({
+            projectId: z.string().min(1),
+            email: z.string().email(),
+            role: z.enum(['owner', 'maintainer', 'member', 'reader']),
+        }),
+    }, async (input) => toolResult(await service.projectMemberAdd(input)));
+    server.registerTool('auth.logout', {
+        description: 'Revoke the refresh session and delete local credentials; transient revoke failures preserve the session unless the user explicitly confirms local-only logout.',
+        inputSchema: z.object({
+            confirmLocalOnly: z.boolean().optional(),
+        }),
+    }, async (input) => toolResult(await service.authLogout(input)));
+    server.registerTool('auth.status', {
+        description: 'Check whether OS credential storage contains an active local Engineering Memory session.',
+        inputSchema: z.object({}),
+    }, async () => toolResult(await service.authStatus()));
+    server.registerTool('auth.signin_browser', {
+        description: 'Start loopback PKCE browser signin and return the URL that Codex or Claude should open for the user. Set restart after an expired, rejected, or otherwise unusable browser link.',
+        inputSchema: z.object({ restart: z.boolean().optional() }),
+    }, async (input) => toolResult(await service.authSigninBrowser(input)));
+}
+function toolResult(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+        isError: !result.ok,
+    };
+}
+//# sourceMappingURL=tool-definitions.js.map

package/runtime/dist/src/project/repository.js

@@ -0,0 +1,79 @@
+import { dirname, join, parse, resolve } from 'node:path';
+import { canonicalPath, pathExists, readJson, writeJson } from '../utilities/files.js';
+export class RepositoryResolver {
+    git;
+    markerSchemaVersion;
+    constructor(git, markerSchemaVersion) {
+        this.git = git;
+        this.markerSchemaVersion = markerSchemaVersion;
+    }
+    async resolve(startPath, explicitProjectId) {
+        const repoRoot = await this.git.findRoot(startPath);
+        const markerPath = await this.findMarker(startPath, repoRoot);
+        const marker = markerPath ? await this.readMarker(markerPath, repoRoot) : null;
+        if (explicitProjectId) {
+            assertProjectId(explicitProjectId);
+        }
+        if (explicitProjectId && marker && explicitProjectId !== marker.projectId) {
+            throw new Error('Explicit project does not match the repository marker');
+        }
+        const [repoFingerprint, git] = await Promise.all([
+            this.git.fingerprint(repoRoot),
+            this.git.manifest(repoRoot),
+        ]);
+        return {
+            repoRoot,
+            markerPath,
+            projectId: explicitProjectId ?? marker?.projectId ?? null,
+            schemaVersion: marker?.schemaVersion ?? null,
+            repoFingerprint,
+            git,
+        };
+    }
+    async writeMarker(repoRoot, projectId) {
+        assertProjectId(projectId);
+        const canonicalRoot = await canonicalPath(repoRoot);
+        const markerPath = join(canonicalRoot, '.engineering-memory', 'project.json');
+        await writeJson(markerPath, {
+            projectId,
+            schemaVersion: this.markerSchemaVersion,
+        }, canonicalRoot);
+        return markerPath;
+    }
+    async findMarker(startPath, repoRoot) {
+        let current = await canonicalPath(startPath);
+        const root = await canonicalPath(repoRoot);
+        while (true) {
+            const candidate = join(current, '.engineering-memory', 'project.json');
+            if (await pathExists(candidate, root)) {
+                return candidate;
+            }
+            if (current === root || current === parse(current).root) {
+                return null;
+            }
+            current = dirname(current);
+        }
+    }
+    async readMarker(path, repoRoot) {
+        const marker = await readJson(path, repoRoot);
+        const schemaVersion = marker?.schemaVersion;
+        if (!marker ||
+            typeof marker.projectId !== 'string' ||
+            typeof schemaVersion !== 'number' ||
+            !Number.isInteger(schemaVersion) ||
+            schemaVersion < 1) {
+            throw new Error(`Invalid Engineering Memory project marker: ${resolve(path)}`);
+        }
+        if (schemaVersion > this.markerSchemaVersion) {
+            throw new Error(`Unsupported project marker schema: ${schemaVersion}`);
+        }
+        assertProjectId(marker.projectId);
+        return marker;
+    }
+}
+function assertProjectId(value) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+        throw new Error('Engineering Memory project identifier must be a UUID');
+    }
+}
+//# sourceMappingURL=repository.js.map