@cspeach/cli 0.6.2 → 0.6.4

package/dist/project-context/__tests__/index.test.js

@@ -0,0 +1,133 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { getProjectContext } from '../index.js';
+let root;
+beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'cspeach-pctx-'));
+});
+afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+});
+async function writeFile(rel, content = '') {
+    const full = path.join(root, rel);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, content, 'utf-8');
+}
+describe('getProjectContext — null cases', () => {
+    it('returns null when cwd does not exist and no sap connection given', async () => {
+        const ctx = await getProjectContext(path.join(root, 'nope'));
+        expect(ctx).toBeNull();
+    });
+    it('returns a SAP-only context when cwd is bogus but sapConnection is provided', async () => {
+        const ctx = await getProjectContext(path.join(root, 'nope'), {
+            sapConnection: {
+                alias: 'S4H',
+                system: { sid: 'S4H', release: '2308', abapVersion: '7.58', platform: 'on-premise', host: null },
+                currentTransport: null,
+                activeScope: null,
+                recentObjects: [],
+            },
+        });
+        expect(ctx).not.toBeNull();
+        expect(ctx?.type).toBe('unknown');
+        expect(ctx?.sapConnection?.alias).toBe('S4H');
+        expect(ctx?.git.isRepo).toBe(false);
+        expect(ctx?.index.totalFiles).toBe(0);
+    });
+});
+describe('getProjectContext — unknown project', () => {
+    it('returns an unknown context for a directory that matches no project type', async () => {
+        await writeFile('random.txt', 'just a file');
+        const ctx = await getProjectContext(root);
+        expect(ctx).not.toBeNull();
+        expect(ctx?.type).toBe('unknown');
+        expect(ctx?.root).toBe(root);
+        expect(ctx?.domainObjects).toEqual({ type: 'unknown' });
+        expect(ctx?.index.totalFiles).toBe(1);
+        expect(ctx?.detectedAt).toMatch(/\d{4}-\d{2}-\d{2}T/);
+    });
+});
+describe('getProjectContext — abapgit project', () => {
+    it('assembles a full abapgit context end-to-end', async () => {
+        await writeFile('.abapgit.xml', '<xml/>');
+        await writeFile('src/zfi/zfi_payments/zcl_pay.clas.abap', '');
+        await writeFile('src/zfi/zfi_payments/zif_pay.intf.abap', '');
+        await writeFile('CLAUDE.md', '# project conventions\n\nUse ZCL_ prefix.\n');
+        const ctx = await getProjectContext(root);
+        expect(ctx).not.toBeNull();
+        expect(ctx.type).toBe('abapgit');
+        expect(ctx.conventions.freeText).toContain('ZCL_ prefix');
+        if (ctx.domainObjects.type !== 'abapgit')
+            throw new Error('wrong domain variant');
+        expect(ctx.domainObjects.objects.map((o) => o.name).sort()).toEqual([
+            'ZCL_PAY',
+            'ZIF_PAY',
+        ]);
+        expect(ctx.index.totalFiles).toBeGreaterThan(0);
+    });
+});
+describe('getProjectContext — fiori-ui5 project', () => {
+    it('assembles a Fiori UI5 context with cross-linked controllers + views', async () => {
+        await writeFile('webapp/manifest.json', JSON.stringify({
+            'sap.ui5': {
+                routing: {
+                    routes: [{ name: 'home', pattern: '', target: 'home' }],
+                },
+            },
+        }));
+        await writeFile('ui5.yaml', 'specVersion: "3.0"\n');
+        await writeFile('webapp/controller/Home.controller.js', `Controller.extend("myapp.controller.Home", {});`);
+        await writeFile('webapp/view/Home.view.xml', `<mvc:View controllerName="myapp.controller.Home" />`);
+        const ctx = await getProjectContext(root);
+        expect(ctx?.type).toBe('fiori-ui5');
+        if (ctx?.domainObjects.type !== 'fiori-ui5')
+            throw new Error('wrong domain variant');
+        expect(ctx.domainObjects.routes).toHaveLength(1);
+        expect(ctx.domainObjects.controllers[0].viewPath).toBe('webapp/view/Home.view.xml');
+        expect(ctx.domainObjects.views[0].controllerPath).toBe('webapp/controller/Home.controller.js');
+    });
+});
+describe('getProjectContext — cap-node project', () => {
+    it('assembles a CAP context with services + entities', async () => {
+        await writeFile('package.json', JSON.stringify({ dependencies: { '@sap/cds': '^7.0.0' } }));
+        await writeFile('db/schema.cds', 'entity Books { key ID : Integer; }');
+        await writeFile('srv/cat.cds', 'service CatalogService { entity Books; }');
+        const ctx = await getProjectContext(root);
+        expect(ctx?.type).toBe('cap-node');
+        if (ctx?.domainObjects.type !== 'cap-node')
+            throw new Error('wrong domain variant');
+        expect(ctx.domainObjects.services.map((s) => s.name)).toEqual(['CatalogService']);
+        expect(ctx.domainObjects.entities.map((e) => e.name).sort()).toContain('Books');
+    });
+});
+describe('getProjectContext — mixed (mta.yaml)', () => {
+    it('returns a mixed-type stub for now (recursive sub-context is Phase 2+)', async () => {
+        await writeFile('mta.yaml', 'ID: my.mta\nversion: 1.0.0\nmodules: []\n');
+        const ctx = await getProjectContext(root);
+        expect(ctx?.type).toBe('mixed');
+        expect(ctx?.domainObjects).toEqual({ type: 'mixed', modules: [] });
+    });
+});
+describe('getProjectContext — sapConnection passthrough', () => {
+    it('attaches sapConnection to a disk project when provided', async () => {
+        await writeFile('.abapgit.xml', '<xml/>');
+        await writeFile('src/zhello.prog.abap', '');
+        const sapConnection = {
+            alias: 'PROD_DEV',
+            system: { sid: 'PRD', release: '2308', abapVersion: '7.58', platform: 'on-premise', host: null },
+            currentTransport: 'PRDK900456',
+            activeScope: null,
+            recentObjects: [],
+        };
+        const ctx = await getProjectContext(root, { sapConnection });
+        expect(ctx?.sapConnection).toBe(sapConnection);
+        expect(ctx?.type).toBe('abapgit');
+    });
+    it('defaults sapConnection to null when option omitted', async () => {
+        await writeFile('random.txt');
+        const ctx = await getProjectContext(root);
+        expect(ctx?.sapConnection).toBeNull();
+    });
+});

package/dist/project-context/__tests__/render.test.js

@@ -0,0 +1,322 @@
+import { describe, it, expect } from 'vitest';
+import { renderProjectContext } from '../render.js';
+function baseContext(overrides = {}) {
+    return {
+        type: 'unknown',
+        root: '/projects/sample',
+        conventions: {
+            freeText: null,
+            namingPatterns: { classes: [], interfaces: [], cdsViews: [] },
+            style: { indentSize: 2, indentChar: 'space', eol: 'lf' },
+        },
+        index: {
+            totalFiles: 0,
+            byExtension: {},
+            topLevelDirs: [],
+            paths: [],
+            truncated: false,
+        },
+        entryPoints: [],
+        domainObjects: { type: 'unknown' },
+        git: { isRepo: false, branch: null, headSha: null, dirtyFileCount: 0, recentCommits: [] },
+        sapConnection: null,
+        detectedAt: '2026-05-10T10:00:00.000Z',
+        ...overrides,
+    };
+}
+describe('renderProjectContext — null handling', () => {
+    it('returns empty string for null context', () => {
+        expect(renderProjectContext(null)).toBe('');
+    });
+    it('renders a minimal unknown context as a valid block', () => {
+        const out = renderProjectContext(baseContext());
+        expect(out).toContain('<project_context type="unknown">');
+        expect(out).toContain('</project_context>');
+        expect(out).toContain('<root>/projects/sample</root>');
+        expect(out).toContain('<git is_repo="false" />');
+        expect(out).toContain('<domain_objects type="unknown" />');
+    });
+});
+describe('renderProjectContext — conventions', () => {
+    it('renders style + naming + truncated freeText', () => {
+        const longText = 'A'.repeat(2000);
+        const out = renderProjectContext(baseContext({
+            conventions: {
+                freeText: longText,
+                namingPatterns: { classes: ['ZCL_'], interfaces: ['ZIF_'], cdsViews: ['ZI_', 'ZC_'] },
+                style: { indentSize: 4, indentChar: 'tab', eol: 'crlf' },
+            },
+        }));
+        expect(out).toContain('<style indent="4 tabs" eol="CRLF" />');
+        expect(out).toContain('<classes>ZCL_</classes>');
+        expect(out).toContain('<cds_views>ZI_, ZC_</cds_views>');
+        expect(out).toContain('truncated');
+        // freeText should be capped — the rendered output must be far less
+        // than the 2000 chars of input.
+        expect(out.length).toBeLessThan(2000 + 500);
+    });
+    it('renders the default 2-space indent in unambiguous form (regression)', () => {
+        // 2026-05-10 dogfooding: the earlier "2sp" packed-token form was
+        // mis-parsed by the model as "1-space indent." The human-readable
+        // "2 spaces" form leaves no room for misinterpretation.
+        const out = renderProjectContext(baseContext()); // default convention is 2-space LF
+        expect(out).toContain('<style indent="2 spaces" eol="LF" />');
+        expect(out).not.toContain('"2sp"');
+    });
+    it('uses singular "space" / "tab" for indent size 1', () => {
+        const out = renderProjectContext(baseContext({
+            conventions: {
+                freeText: null,
+                namingPatterns: { classes: [], interfaces: [], cdsViews: [] },
+                style: { indentSize: 1, indentChar: 'tab', eol: 'lf' },
+            },
+        }));
+        expect(out).toContain('<style indent="1 tab" eol="LF" />');
+    });
+});
+describe('renderProjectContext — git', () => {
+    it('renders branch + sha + dirty + recent commits when in a repo', () => {
+        const out = renderProjectContext(baseContext({
+            git: {
+                isRepo: true,
+                branch: 'main',
+                headSha: 'abcd1234',
+                dirtyFileCount: 3,
+                recentCommits: ['1111111 first', '2222222 second'],
+            },
+        }));
+        expect(out).toContain('<git is_repo="true">');
+        expect(out).toContain('<branch>main</branch>');
+        expect(out).toContain('<head_sha>abcd1234</head_sha>');
+        expect(out).toContain('<dirty_files>3</dirty_files>');
+        expect(out).toContain('1111111 first');
+        expect(out).toContain('2222222 second');
+    });
+});
+describe('renderProjectContext — file index', () => {
+    it('renders top-level dirs + extension summary + capped paths', () => {
+        const paths = Array.from({ length: 200 }, (_, i) => `src/file-${i}.ts`);
+        const out = renderProjectContext(baseContext({
+            index: {
+                totalFiles: 200,
+                byExtension: { '.ts': 200, '.md': 5 },
+                topLevelDirs: ['src', 'docs'],
+                paths,
+                truncated: false,
+            },
+        }));
+        expect(out).toContain('<top_level_dirs>src, docs</top_level_dirs>');
+        expect(out).toContain('.ts=200');
+        expect(out).toContain('src/file-0.ts');
+        // Paths cap is 60 — must include a "more" marker.
+        expect(out).toContain('more — search via glob');
+        expect(out).not.toContain('src/file-199.ts');
+    });
+    it('emits truncated="true" attribute when index truncation flag is set', () => {
+        const out = renderProjectContext(baseContext({
+            index: { totalFiles: 12000, byExtension: {}, topLevelDirs: [], paths: [], truncated: true },
+        }));
+        expect(out).toContain('<file_index total="12000" truncated="true">');
+    });
+});
+describe('renderProjectContext — domain renderers', () => {
+    it('renders fiori-ui5 with controllers/views/routes/i18n', () => {
+        const out = renderProjectContext(baseContext({
+            type: 'fiori-ui5',
+            domainObjects: {
+                type: 'fiori-ui5',
+                controllers: [
+                    { name: 'Worklist', path: 'webapp/controller/Worklist.controller.js', viewPath: 'webapp/view/Worklist.view.xml', i18nKeys: ['title'] },
+                ],
+                views: [
+                    { name: 'Worklist', path: 'webapp/view/Worklist.view.xml', controllerPath: 'webapp/controller/Worklist.controller.js', boundModelPaths: [] },
+                ],
+                routes: [{ name: 'home', pattern: '', targets: ['main'] }],
+                i18nKeys: ['title', 'description'],
+            },
+        }));
+        expect(out).toContain('<domain_objects type="fiori-ui5">');
+        expect(out).toContain('<route name="home"');
+        expect(out).toContain('<controller name="Worklist"');
+        expect(out).toContain('view="webapp/view/Worklist.view.xml"');
+        expect(out).toContain('<i18n_keys>title, description</i18n_keys>');
+    });
+    it('renders cap-node with services + entities', () => {
+        const out = renderProjectContext(baseContext({
+            type: 'cap-node',
+            domainObjects: {
+                type: 'cap-node',
+                services: [{ name: 'CatalogService', path: 'srv/cat.cds', entities: ['Books', 'Authors'] }],
+                entities: [
+                    { name: 'Books', path: 'db/schema.cds', source: null },
+                    { name: 'External', path: 'db/ext.cds', source: 'external-table' },
+                ],
+            },
+        }));
+        expect(out).toContain('<service name="CatalogService"');
+        expect(out).toContain('entities="Books,Authors"');
+        expect(out).toContain('<entity name="Books"');
+        expect(out).toContain('source="external-table"');
+    });
+    it('renders abapgit with package + cap marker', () => {
+        const objects = Array.from({ length: 100 }, (_, i) => ({
+            name: `ZCL_OBJ_${i.toString().padStart(3, '0')}`,
+            type: 'CLAS',
+            path: `src/obj-${i}.clas.abap`,
+            package: 'ZTEST',
+        }));
+        const out = renderProjectContext(baseContext({
+            type: 'abapgit',
+            domainObjects: { type: 'abapgit', objects },
+        }));
+        expect(out).toContain('<domain_objects type="abapgit" total="100">');
+        expect(out).toContain('<object name="ZCL_OBJ_000"');
+        expect(out).toContain('package="ZTEST"');
+        expect(out).toContain('20 more objects — search via glob');
+        expect(out).not.toContain('ZCL_OBJ_099');
+    });
+    it('renders abap-cloud with behavior definitions promoted', () => {
+        const out = renderProjectContext(baseContext({
+            type: 'abap-cloud',
+            domainObjects: {
+                type: 'abap-cloud',
+                objects: [
+                    { name: 'ZR_ORDER', type: 'BDEF', path: 'src/zr_order.bdef.asbdef', package: null },
+                    { name: 'ZBP_ZR_ORDER', type: 'CLAS', path: 'src/zbp_zr_order.clas.abap', package: null },
+                ],
+                behaviorDefinitions: ['ZR_ORDER'],
+            },
+        }));
+        expect(out).toContain('behavior_definitions="1"');
+        expect(out).toContain('<bdefs>ZR_ORDER</bdefs>');
+        expect(out).toContain('<object name="ZBP_ZR_ORDER"');
+    });
+    it('renders mixed type with module count', () => {
+        const out = renderProjectContext(baseContext({
+            type: 'mixed',
+            domainObjects: { type: 'mixed', modules: [] },
+        }));
+        expect(out).toContain('<domain_objects type="mixed" modules="0" />');
+    });
+});
+describe('renderProjectContext — sap connection', () => {
+    it('renders sap_connection block when connection is present', () => {
+        const out = renderProjectContext(baseContext({
+            sapConnection: {
+                alias: 'S4H',
+                system: { sid: 'S4H', release: '2308', abapVersion: '7.58', platform: 'on-premise', host: 'sap.example.com' },
+                currentTransport: 'S4HK900123',
+                activeScope: { package: 'ZFI_PAYMENTS', object: { name: 'ZCL_PAY', type: 'CLAS' } },
+                recentObjects: [
+                    { name: 'ZCL_PAY', type: 'CLAS', lastTouchedAt: '2026-05-10T10:00:00Z', lastAction: 'read' },
+                ],
+            },
+        }));
+        expect(out).toContain('<sap_connection alias="S4H">');
+        expect(out).toContain('sid="S4H"');
+        expect(out).toContain('release="2308"');
+        expect(out).toContain('<current_transport>S4HK900123</current_transport>');
+        expect(out).toContain('<active_package>ZFI_PAYMENTS</active_package>');
+        expect(out).toContain('<active_object name="ZCL_PAY"');
+        expect(out).toContain('<object name="ZCL_PAY" type="CLAS" action="read" />');
+    });
+});
+describe('renderProjectContext — escaping', () => {
+    it('escapes XML special characters in values', () => {
+        const out = renderProjectContext(baseContext({
+            root: '/path/with <angle> & "quotes"',
+        }));
+        expect(out).toContain('/path/with &lt;angle&gt; &amp; "quotes"');
+    });
+    it('escapes XML inside conventions.freeText (realistic CLAUDE.md content)', () => {
+        // This very repo's CLAUDE.md contains literal XML snippets like
+        // <asx:values>, <atc:run>, <objectSet>. Without escaping, those
+        // would break <project_context> well-formedness when the freeText
+        // body is spliced into the system prompt.
+        const realFreeText = [
+            '## Critical Patterns',
+            '',
+            '**Lock handle parsing:** SAP returns `<LOCK_HANDLE>` (uppercase) inside `<asx:values><DATA>`.',
+            '**ATC run XML:** Use `<objectSet kind="inclusive">` (no namespace prefix). Use `<atc:run>` not `<atcinfo:run>`.',
+            'Special chars: & < > should all survive escaping.',
+        ].join('\n');
+        const out = renderProjectContext(baseContext({
+            conventions: {
+                freeText: realFreeText,
+                namingPatterns: { classes: [], interfaces: [], cdsViews: [] },
+                style: { indentSize: 2, indentChar: 'space', eol: 'lf' },
+            },
+        }));
+        // The literal XML must NOT appear in the output as raw tags — it
+        // must be entity-escaped so it can't close <freeText> early.
+        expect(out).not.toContain('<asx:values>');
+        expect(out).not.toContain('<atc:run>');
+        expect(out).not.toContain('<objectSet kind=');
+        expect(out).toContain('&lt;asx:values&gt;');
+        expect(out).toContain('&lt;atc:run&gt;');
+        // Bare ampersand must also escape.
+        expect(out).toContain('&amp; &lt; &gt;');
+        // The opening/closing tags of OUR block remain intact.
+        expect(out).toContain('<freeText>');
+        expect(out).toContain('</freeText>');
+    });
+    it('escapes XML in namingPatterns + topLevelDirs + by_extension', () => {
+        const out = renderProjectContext(baseContext({
+            conventions: {
+                freeText: null,
+                // Synthetic but representative: a custom override could put
+                // anything here; we must not trust it inside element bodies.
+                namingPatterns: { classes: ['Z<bad>_'], interfaces: ['Z&_'], cdsViews: [] },
+                style: { indentSize: 2, indentChar: 'space', eol: 'lf' },
+            },
+            index: {
+                totalFiles: 1,
+                byExtension: { '.<x>': 1, '.&y': 1 },
+                topLevelDirs: ['weird<dir>', 'a&b'],
+                paths: [],
+                truncated: false,
+            },
+        }));
+        expect(out).not.toContain('Z<bad>_');
+        expect(out).toContain('Z&lt;bad&gt;_');
+        expect(out).toContain('Z&amp;_');
+        expect(out).toContain('weird&lt;dir&gt;');
+        expect(out).toContain('a&amp;b');
+        expect(out).toContain('.&lt;x&gt;=1');
+        expect(out).toContain('.&amp;y=1');
+    });
+});
+describe('renderProjectContext — rough size budget', () => {
+    it('stays under ~13000 chars on a high-end project (~3.25K tokens)', () => {
+        const ctrls = Array.from({ length: 60 }, (_, i) => ({
+            name: `Ctl${i}`,
+            path: `webapp/controller/Ctl${i}.controller.js`,
+            viewPath: `webapp/view/Ctl${i}.view.xml`,
+            i18nKeys: ['k1', 'k2'],
+        }));
+        const views = Array.from({ length: 60 }, (_, i) => ({
+            name: `Ctl${i}`,
+            path: `webapp/view/Ctl${i}.view.xml`,
+            controllerPath: `webapp/controller/Ctl${i}.controller.js`,
+            boundModelPaths: ['/data/items'],
+        }));
+        const routes = Array.from({ length: 60 }, (_, i) => ({
+            name: `route${i}`,
+            pattern: `r/${i}`,
+            targets: [`t${i}`],
+        }));
+        const i18n = Array.from({ length: 200 }, (_, i) => `key${i}`);
+        const paths = Array.from({ length: 500 }, (_, i) => `webapp/file-${i}.js`);
+        const out = renderProjectContext(baseContext({
+            type: 'fiori-ui5',
+            conventions: {
+                freeText: 'B'.repeat(500),
+                namingPatterns: { classes: [], interfaces: [], cdsViews: [] },
+                style: { indentSize: 2, indentChar: 'space', eol: 'lf' },
+            },
+            index: { totalFiles: 500, byExtension: { '.js': 500 }, topLevelDirs: ['webapp'], paths, truncated: false },
+            domainObjects: { type: 'fiori-ui5', controllers: ctrls, views, routes, i18nKeys: i18n },
+        }));
+        expect(out.length).toBeLessThan(13000);
+    });
+});

package/dist/project-context/__tests__/types.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect, expectTypeOf } from 'vitest';
+import { getProjectContext } from '../index.js';
+describe('project-context types — Phase 1A scaffolding', () => {
+    it('ProjectType enumerates the six supported project shapes', () => {
+        expectTypeOf().toEqualTypeOf();
+    });
+    it('ProjectConventions has freeText, namingPatterns, style', () => {
+        expectTypeOf().toMatchTypeOf();
+    });
+    it('FileIndex caps + truncation flag are part of the shape', () => {
+        expectTypeOf().toMatchTypeOf();
+    });
+    it('DomainObjectIndex is type-discriminated', () => {
+        // Each project type has its own domain-object shape. Compile-time
+        // discrimination prevents callers from accidentally accessing
+        // controllers[] on a CAP project or services[] on a Fiori project.
+        const fiori = {
+            type: 'fiori-ui5',
+            controllers: [],
+            views: [],
+            routes: [],
+            i18nKeys: [],
+        };
+        expect(fiori.type).toBe('fiori-ui5');
+        const cap = {
+            type: 'cap-node',
+            services: [],
+            entities: [],
+        };
+        expect(cap.type).toBe('cap-node');
+        const abapgit = {
+            type: 'abapgit',
+            objects: [],
+        };
+        expect(abapgit.type).toBe('abapgit');
+        const cloud = {
+            type: 'abap-cloud',
+            objects: [],
+            behaviorDefinitions: [],
+        };
+        expect(cloud.type).toBe('abap-cloud');
+        const unknown = { type: 'unknown' };
+        expect(unknown.type).toBe('unknown');
+    });
+    it('GitState carries branch + dirty count + recent commits', () => {
+        expectTypeOf().toMatchTypeOf();
+    });
+    it('ProjectContext aggregates everything + a detectedAt timestamp', () => {
+        expectTypeOf().toMatchTypeOf();
+    });
+    it('ProjectContext.sapConnection is nullable — classical ABAP live work surfaces here', async () => {
+        // Live-SAP classical ABAP work has no on-disk project but DOES
+        // have a project: the SAP system + active package + recent objects.
+        // sapConnection is where that lives. Most CSPeach users today are
+        // in this mode — connected to a system, no disk project.
+        const { SapConnectionContext } = await import('../types.js')
+            .then((m) => ({ SapConnectionContext: null }))
+            .catch(() => ({ SapConnectionContext: null }));
+        expectTypeOf().toMatchTypeOf();
+        expect(SapConnectionContext).toBeNull(); // The placeholder import; just exercising the module load.
+    });
+});
+describe('getProjectContext — null contract', () => {
+    // Phase 1F implementation. Detailed behavior tests live in index.test.ts.
+    // These tests pin down the null-safety invariant only.
+    it('returns null when cwd is unreadable / does not exist', async () => {
+        expect(await getProjectContext('/nonexistent/path/that/cannot/exist')).toBeNull();
+    });
+    it('never throws on hostile input — null contract is the safety net', async () => {
+        await expect(getProjectContext('\0\0\0')).resolves.toBeNull();
+        await expect(getProjectContext('/nonexistent/path/that/cannot/exist')).resolves.toBeNull();
+    });
+});

package/dist/projects/__tests__/build.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { buildEnvelope } from '../build.js';
+const SAMPLE_EXTRACT = {
+    title: 'Customer Aging Report',
+    content: { inputType: 'User Story', inferredDomain: 'FI-AR', sections: [
+            { name: 'Missing Business Questions', audience: 'business', gaps: [
+                    { id: 'gap-001', severity: 'BLOCKER', text: 'What defines "open"?' },
+                ] },
+        ] },
+    items: [{ id: 'gap-001', status: 'open', answer: null, answeredBy: null, answeredAt: null, comments: [] }],
+};
+describe('buildEnvelope', () => {
+    it('assembles a v1 envelope with version=1, history=[created]', () => {
+        const env = buildEnvelope({
+            artefactType: 'spec-gap',
+            extract: SAMPLE_EXTRACT,
+            author: { name: 'Laeeq', role: 'consultant' },
+            source: { skill: 'abap-spec-gap', skillVersion: '1.0', input: '...', tokensUsed: 5000, model: 'claude-opus-4-7' },
+        });
+        expect(env.schemaVersion).toBe('1.0');
+        expect(env.artefactType).toBe('spec-gap');
+        expect(env.title).toBe('Customer Aging Report');
+        expect(env.version).toBe(1);
+        expect(env.history).toHaveLength(1);
+        expect(env.history[0].action).toBe('created');
+        expect(env.history[0].by).toEqual({ name: 'Laeeq', role: 'consultant' });
+        expect(env.createdBy).toEqual(env.lastEditedBy);
+        expect(env.createdAt).toBe(env.lastEditedAt);
+        expect(env.promotedFrom).toBeNull();
+        expect(env.interaction.items).toHaveLength(1);
+    });
+    it('generates a UUID v4 id', () => {
+        const env = buildEnvelope({
+            artefactType: 'spec-gap',
+            extract: SAMPLE_EXTRACT,
+            author: { name: 'Laeeq', role: 'consultant' },
+            source: { skill: 'abap-spec-gap', skillVersion: '1.0', input: '...', tokensUsed: 5000, model: 'claude-opus-4-7' },
+        });
+        expect(env.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+    });
+    it('produces a validatable envelope', async () => {
+        const { validateEnvelope } = await import('../validate.js');
+        const env = buildEnvelope({
+            artefactType: 'spec-gap',
+            extract: SAMPLE_EXTRACT,
+            author: { name: 'Laeeq', role: 'consultant' },
+            source: { skill: 'abap-spec-gap', skillVersion: '1.0', input: '...', tokensUsed: 5000, model: 'claude-opus-4-7' },
+        });
+        const result = validateEnvelope(env);
+        expect(result.ok).toBe(true);
+    });
+});

package/dist/projects/__tests__/canonicalize.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { canonicalSha256 } from '../canonicalize.js';
+const baseEnv = {
+    schemaVersion: '1.0',
+    artefactType: 'spec-gap',
+    id: '11111111-1111-4111-8111-111111111111',
+    title: 'Customer Aging Report',
+    createdAt: '2026-05-03T12:00:00Z',
+    createdBy: { name: 'Laeeq', role: 'consultant' },
+    lastEditedAt: '2026-05-04T10:00:00Z',
+    lastEditedBy: { name: 'Laeeq', role: 'consultant' },
+    version: 1,
+    source: { skill: 'abap-spec-gap', skillVersion: '1.0', input: '...', tokensUsed: 100, model: 'm' },
+    promotedFrom: null,
+    content: { inputType: 'User Story', inferredDomain: 'FI-AR', sections: [] },
+    interaction: { items: [] },
+    history: [{ at: '2026-05-03T12:00:00Z', by: { name: 'Laeeq', role: 'consultant' }, action: 'created' }],
+};
+describe('canonicalSha256', () => {
+    it('produces a 64-char hex hash', async () => {
+        const hash = await canonicalSha256(baseEnv);
+        expect(hash).toMatch(/^[0-9a-f]{64}$/);
+    });
+    it('is stable across object key order', async () => {
+        const reordered = { ...baseEnv, version: 1, schemaVersion: '1.0' };
+        expect(await canonicalSha256(baseEnv)).toBe(await canonicalSha256(reordered));
+    });
+    it('ignores changes to lastEditedAt', async () => {
+        const sameContent = { ...baseEnv, lastEditedAt: '2099-12-31T23:59:59Z' };
+        expect(await canonicalSha256(baseEnv)).toBe(await canonicalSha256(sameContent));
+    });
+    it('ignores changes to history[*].at', async () => {
+        const sameContent = {
+            ...baseEnv,
+            history: [{ at: '2099-12-31T23:59:59Z', by: { name: 'Laeeq', role: 'consultant' }, action: 'created' }],
+        };
+        expect(await canonicalSha256(baseEnv)).toBe(await canonicalSha256(sameContent));
+    });
+    it('changes when answer text changes', async () => {
+        const withAnswer = {
+            ...baseEnv,
+            interaction: { items: [{ id: 'gap-001', status: 'answered', answer: 'BSID',
+                        answeredBy: { name: 'Sarah', role: 'BA' }, answeredAt: '2026-05-04T10:00:00Z', comments: [] }] },
+        };
+        expect(await canonicalSha256(baseEnv)).not.toBe(await canonicalSha256(withAnswer));
+    });
+});