proteum 2.2.3 → 2.2.7

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.2.3",
+	"version": "2.2.7",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/services/router/request/index.ts

@@ -17,6 +17,7 @@ import type { HttpMethod, HttpHeaders } from '..';
 import ApiClient from './api';
 import ServerResponse from '../response';
 import type { TAnyRouter } from '..';
+import { resolveRequestIp } from './ip';
 
 /*----------------------------------
 - TYPES
@@ -42,24 +43,6 @@ type TRequestTraceCallContext = {
     label: string;
     origin: TTraceCallOrigin;
 };
-type THeaderValue = string | string[] | undefined;
-
-const readHeader = (headers: Record<string, THeaderValue>, name: string): string | null => {
-    const exact = headers[name];
-    const alternate = exact === undefined ? headers[name.toLowerCase()] : exact;
-    const value = alternate === undefined ? headers[name.toUpperCase()] : alternate;
-
-    if (Array.isArray(value)) {
-        const firstValue = value.find((entry) => typeof entry === 'string' && entry.trim());
-        return typeof firstValue === 'string' ? firstValue.trim() : null;
-    }
-
-    return typeof value === 'string' && value.trim() ? value.trim() : null;
-};
-
-const resolveRequestIp = (req: express.Request): string | undefined => {
-    return readHeader(req.headers as Record<string, THeaderValue>, 'cf-connecting-ip') || req.ip;
-};
 
 /*----------------------------------
 - CONTEXTE

package/server/services/router/request/ip.test.cjs

@@ -0,0 +1,60 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const { resolveRequestIp } = require('./ip.ts');
+
+const request = (headers, ip = '192.0.2.10') => ({
+    headers,
+    ip,
+});
+
+test('Cloudflare client IP wins over Express fallback IP', () => {
+    assert.equal(
+        resolveRequestIp(request({ 'cf-connecting-ip': '203.0.113.10' }, '192.0.2.10')),
+        '203.0.113.10',
+    );
+});
+
+test('True-Client-IP wins when Cloudflare IP is absent', () => {
+    assert.equal(
+        resolveRequestIp(request({ 'true-client-ip': '198.51.100.24' }, '192.0.2.10')),
+        '198.51.100.24',
+    );
+});
+
+test('Fastly-Client-IP wins when Cloudflare and True-Client-IP are absent', () => {
+    assert.equal(
+        resolveRequestIp(request({ 'fastly-client-ip': '51.182.144.154' }, '192.0.2.10')),
+        '51.182.144.154',
+    );
+});
+
+test('invalid and spoof-looking values are ignored before falling back to Express IP', () => {
+    assert.equal(
+        resolveRequestIp(
+            request(
+                {
+                    'cf-connecting-ip': 'not-an-ip',
+                    'true-client-ip': '203.0.113.10, 198.51.100.24',
+                    'fastly-client-ip': 'unknown',
+                    'x-forwarded-for': '203.0.113.200',
+                    forwarded: 'for=203.0.113.201',
+                },
+                '192.0.2.10',
+            ),
+        ),
+        '192.0.2.10',
+    );
+});
+
+test('IPv4-mapped IPv6 and bracketed IPv6 candidates normalize correctly', () => {
+    assert.equal(
+        resolveRequestIp(request({ 'fastly-client-ip': ' ::ffff:51.182.144.154 ' }, '192.0.2.10')),
+        '51.182.144.154',
+    );
+    assert.equal(resolveRequestIp(request({ 'true-client-ip': '[2001:db8::12]' }, '192.0.2.10')), '2001:db8::12');
+});
+
+test('IPv4 port suffix candidates normalize correctly', () => {
+    assert.equal(resolveRequestIp(request({ 'fastly-client-ip': '51.182.144.154:443' }, '192.0.2.10')), '51.182.144.154');
+});

package/server/services/router/request/ip.ts

@@ -0,0 +1,71 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import type express from 'express';
+import { isIP } from 'net';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+type THeaderValue = string | string[] | undefined;
+
+/*----------------------------------
+- CONSTANTS
+----------------------------------*/
+
+const trustedClientIpHeaders = ['cf-connecting-ip', 'true-client-ip', 'fastly-client-ip'] as const;
+const bracketedIpPattern = /^\[([^\]]+)\](?::\d+)?$/;
+const ipv4WithPortPattern = /^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/;
+const ipv4MappedIpv6Pattern = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i;
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const readHeader = (headers: Record<string, THeaderValue>, name: string): string | null => {
+    const normalizedName = name.toLowerCase();
+    const directValue = headers[name] ?? headers[normalizedName] ?? headers[name.toUpperCase()];
+    const value =
+        directValue !== undefined
+            ? directValue
+            : Object.entries(headers).find(([key]) => key.toLowerCase() === normalizedName)?.[1];
+
+    if (Array.isArray(value)) {
+        const firstValue = value.find((entry) => typeof entry === 'string' && entry.trim());
+        return typeof firstValue === 'string' ? firstValue.trim() : null;
+    }
+
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+};
+
+export const normalizeRequestIpCandidate = (value: string | null | undefined): string | null => {
+    let candidate = typeof value === 'string' ? value.trim() : '';
+    if (!candidate) return null;
+
+    const bracketedIp = bracketedIpPattern.exec(candidate);
+    if (bracketedIp) candidate = bracketedIp[1].trim();
+
+    const ipv4MappedIpv6 = ipv4MappedIpv6Pattern.exec(candidate);
+    if (ipv4MappedIpv6 && isIP(ipv4MappedIpv6[1]) === 4) {
+        candidate = ipv4MappedIpv6[1];
+    } else {
+        const ipv4WithPort = ipv4WithPortPattern.exec(candidate);
+        if (ipv4WithPort && isIP(ipv4WithPort[1]) === 4) candidate = ipv4WithPort[1];
+    }
+
+    return isIP(candidate) ? candidate : null;
+};
+
+export const resolveRequestIp = (req: Pick<express.Request, 'headers' | 'ip'>): string | undefined => {
+    const headers = req.headers as Record<string, THeaderValue>;
+
+    for (const headerName of trustedClientIpHeaders) {
+        const ip = normalizeRequestIpCandidate(readHeader(headers, headerName));
+        if (ip) return ip;
+    }
+
+    return normalizeRequestIpCandidate(req.ip) || undefined;
+};

package/tests/agents-utils.test.cjs

@@ -0,0 +1,207 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const { configureProjectAgentInstructions, resolveProjectAgentMonorepoRoot } = require('../cli/utils/agents.ts');
+
+const writeFile = (filepath, content) => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+const makeTempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-agents-'));
+
+const createCoreFixture = () => {
+    const root = makeTempRoot();
+    const agentsRoot = path.join(root, 'agents', 'project');
+
+    writeFile(path.join(agentsRoot, 'AGENTS.md'), '# Root Contract\n\n- Root rule\n');
+    writeFile(path.join(agentsRoot, 'CODING_STYLE.md'), '# Coding Style\n\n- Style rule\n');
+    writeFile(path.join(agentsRoot, 'client', 'AGENTS.md'), '# Client Rules\n\n- Client rule\n');
+
+    return root;
+};
+
+const createAppFixture = () => {
+    const appRoot = makeTempRoot();
+
+    for (const dir of ['client/pages', 'server/routes', 'server/services', 'tests/e2e']) {
+        fs.mkdirSync(path.join(appRoot, dir), { recursive: true });
+    }
+
+    writeFile(
+        path.join(appRoot, '.gitignore'),
+        [
+            'node_modules',
+            '# Proteum-managed instruction files',
+            '/AGENTS.md',
+            '/CODING_STYLE.md',
+            '# End Proteum-managed instruction files',
+            '/.proteum',
+            '',
+        ].join('\n'),
+    );
+
+    return appRoot;
+};
+
+test('standalone configure creates tracked instruction files with embedded corpus', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot });
+    const agentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    const codingStyleContent = fs.readFileSync(path.join(appRoot, 'CODING_STYLE.md'), 'utf8');
+    const gitignoreContent = fs.readFileSync(path.join(appRoot, '.gitignore'), 'utf8');
+
+    assert.equal(result.blocked.length, 0);
+    assert.match(agentsContent, /^# Proteum Instructions/m);
+    assert.match(agentsContent, /<!-- proteum-instructions:start -->/);
+    assert.match(agentsContent, /## Source: AGENTS\.md/);
+    assert.match(agentsContent, /## Root Contract/);
+    assert.match(agentsContent, /## Source: CODING_STYLE\.md/);
+    assert.match(codingStyleContent, /## Source: client\/AGENTS\.md/);
+    assert.doesNotMatch(agentsContent, /Before reading or applying instructions from this file/);
+    assert.doesNotMatch(gitignoreContent, /Proteum-managed instruction files/);
+    assert.doesNotMatch(gitignoreContent, /^\/AGENTS\.md$/m);
+});
+
+test('configure preserves project content outside the managed section', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+
+    writeFile(
+        path.join(appRoot, 'AGENTS.md'),
+        [
+            '# Product Notes',
+            '',
+            'Keep this product note.',
+            '',
+            '# Proteum Instructions',
+            '<!-- proteum-instructions:start -->',
+            '',
+            'Old managed content.',
+            '',
+            '<!-- proteum-instructions:end -->',
+            '',
+            '# Local Footer',
+            '',
+            'Keep this footer.',
+            '',
+        ].join('\n'),
+    );
+
+    configureProjectAgentInstructions({ appRoot, coreRoot });
+
+    const content = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    assert.match(content, /# Product Notes/);
+    assert.match(content, /Keep this product note\./);
+    assert.match(content, /## Source: CODING_STYLE\.md/);
+    assert.doesNotMatch(content, /Old managed content/);
+    assert.match(content, /# Local Footer/);
+    assert.match(content, /Keep this footer\./);
+});
+
+test('configure preserves project content around legacy managed stubs', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+
+    writeFile(
+        path.join(appRoot, 'AGENTS.md'),
+        [
+            '## Product Bootstrap',
+            '',
+            'Keep these local bootstrap notes.',
+            '',
+            '# Proteum Managed Instructions',
+            '',
+            'This file is managed by `proteum configure agents`.',
+            '',
+            'Before reading or applying instructions from this file, read and follow the canonical Proteum instruction file at:',
+            '',
+            '`node_modules/proteum/agents/project/AGENTS.md`',
+            '',
+            'Resolve that path relative to this file. Treat the canonical file as if its full contents were written here.',
+            '',
+            'If the canonical file cannot be read, stop and run `npx proteum configure agents` before continuing.',
+            '',
+            '## Local Footer',
+            '',
+            'Keep this footer too.',
+            '',
+        ].join('\n'),
+    );
+
+    configureProjectAgentInstructions({ appRoot, coreRoot });
+
+    const content = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    assert.match(content, /## Product Bootstrap/);
+    assert.match(content, /Keep these local bootstrap notes\./);
+    assert.match(content, /# Proteum Instructions/);
+    assert.match(content, /## Source: CODING_STYLE\.md/);
+    assert.doesNotMatch(content, /# Proteum Managed Instructions/);
+    assert.doesNotMatch(content, /Before reading or applying instructions from this file/);
+    assert.match(content, /## Local Footer/);
+    assert.match(content, /Keep this footer too\./);
+});
+
+test('monorepo configure writes root and app instruction files', () => {
+    const coreRoot = createCoreFixture();
+    const monorepoRoot = makeTempRoot();
+    const appRoot = path.join(monorepoRoot, 'apps', 'product');
+
+    fs.mkdirSync(path.join(monorepoRoot, '.git'));
+    fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot, monorepoRoot });
+
+    assert.equal(result.mode, 'monorepo');
+    assert.equal(resolveProjectAgentMonorepoRoot(appRoot), fs.realpathSync(monorepoRoot));
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Source: AGENTS\.md/);
+    assert.match(fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
+});
+
+test('configure migrates legacy managed symlinks to embedded files', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const installedCoreRoot = createCoreFixture();
+    const target = path.join(installedCoreRoot, 'agents', 'project', 'AGENTS.md');
+    const linkPath = path.join(appRoot, 'AGENTS.md');
+
+    fs.symlinkSync(target, linkPath);
+
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot });
+    const stats = fs.lstatSync(linkPath);
+    const content = fs.readFileSync(linkPath, 'utf8');
+
+    assert.equal(result.updated.some((entry) => entry.endsWith('/AGENTS.md')), true);
+    assert.equal(stats.isSymbolicLink(), false);
+    assert.match(content, /# Proteum Instructions/);
+});
+
+test('configure reports blocked paths unless overwrite is allowed', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const blockedPath = path.join(appRoot, 'CODING_STYLE.md');
+
+    fs.mkdirSync(blockedPath);
+
+    const preview = configureProjectAgentInstructions({ appRoot, coreRoot, dryRun: true });
+    assert.equal(preview.blocked.some((entry) => entry.endsWith('/CODING_STYLE.md')), true);
+
+    const result = configureProjectAgentInstructions({
+        appRoot,
+        coreRoot,
+        overwriteBlockedPaths: [blockedPath],
+    });
+
+    assert.equal(result.overwritten.some((entry) => entry.endsWith('/CODING_STYLE.md')), true);
+    assert.equal(fs.lstatSync(blockedPath).isFile(), true);
+    assert.match(fs.readFileSync(blockedPath, 'utf8'), /## Source: AGENTS\.md/);
+});