anhedral 0.1.9 → 0.3.0

package/dist/workspace-config.js

@@ -0,0 +1,372 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { SECURITY_OVERRIDES } from './dependencies.js';
+import { writeFile } from './util.js';
+function pathEntryExists(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export function desiredWorkspacePolicy() {
+    return {
+        overrides: { ...SECURITY_OVERRIDES },
+        onlyBuiltDependencies: ['electron', 'esbuild', 'sharp'],
+        ignoredBuiltDependencies: [
+            'browser-tabs-lock',
+            'bufferutil',
+            'core-js',
+            'electron-winstaller',
+            'spawn-sync',
+            'utf-8-validate',
+        ],
+        peerDependencyRules: {
+            ignoreMissing: ['@solana/web3.js', 'bs58', 'react-native'],
+            allowedVersions: {
+                esbuild: '>=0.25.0',
+                'utf-8-validate': '>=5.0.2',
+            },
+        },
+    };
+}
+// Managed pnpm policy intentionally supports only scalar maps and string lists. More complex YAML
+// is left untouched outside managed sections and rejected inside them instead of being guessed at.
+function sourceLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        let cursor = start;
+        while (cursor < content.length && content[cursor] !== '\n' && content[cursor] !== '\r')
+            cursor += 1;
+        const text = content.slice(start, cursor);
+        if (content[cursor] === '\r' && content[cursor + 1] === '\n')
+            cursor += 2;
+        else if (cursor < content.length)
+            cursor += 1;
+        lines.push({ text, start, end: cursor });
+        start = cursor;
+    }
+    return lines;
+}
+function workspaceNewline(content) {
+    return content.includes('\r\n') ? '\r\n' : content.includes('\r') ? '\r' : '\n';
+}
+function parseWorkspaceStringScalar(raw) {
+    const leading = /^[ \t]*/.exec(raw)?.[0].length ?? 0;
+    const valueAndComment = raw.slice(leading);
+    if (!valueAndComment)
+        return null;
+    const singleQuoted = /^'((?:[^']|'')*)'([ \t]*(?:#.*)?)$/.exec(valueAndComment);
+    if (singleQuoted) {
+        return {
+            value: singleQuoted[1].replaceAll("''", "'"),
+            tokenStart: leading,
+            tokenEnd: leading + singleQuoted[0].length - singleQuoted[2].length,
+        };
+    }
+    if (valueAndComment.startsWith("'"))
+        return null;
+    const doubleQuoted = /^("(?:[^"\\]|\\.)*")([ \t]*(?:#.*)?)$/.exec(valueAndComment);
+    if (doubleQuoted) {
+        try {
+            const value = JSON.parse(doubleQuoted[1]);
+            return typeof value === 'string'
+                ? { value, tokenStart: leading, tokenEnd: leading + doubleQuoted[1].length }
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (valueAndComment.startsWith('"'))
+        return null;
+    const comment = /[ \t]+#/.exec(valueAndComment);
+    const withoutComment = valueAndComment.slice(0, comment?.index ?? valueAndComment.length).trimEnd();
+    if (!withoutComment || /^[\[{|>&*!]/.test(withoutComment))
+        return null;
+    if (/^(?:null|~|true|false|[-+]?(?:\.inf|\.nan|0x[\da-f]+|0o[0-7]+|\d+(?:\.\d+)?(?:e[-+]?\d+)?))$/i.test(withoutComment)) {
+        return null;
+    }
+    return { value: withoutComment, tokenStart: leading, tokenEnd: leading + withoutComment.length };
+}
+function parseWorkspaceMapLine(line) {
+    const indent = /^([ \t]*)/.exec(line)?.[1] ?? '';
+    const body = line.slice(indent.length);
+    let match = /^'((?:[^']|'')*)'[ \t]*:/.exec(body);
+    let key;
+    if (match)
+        key = match[1].replaceAll("''", "'");
+    else {
+        match = /^("(?:[^"\\]|\\.)*")[ \t]*:/.exec(body);
+        if (match) {
+            try {
+                const parsed = JSON.parse(match[1]);
+                if (typeof parsed !== 'string')
+                    return null;
+                key = parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        else {
+            match = /^([^:#][^:]*?)[ \t]*:/.exec(body);
+            if (!match)
+                return null;
+            key = match[1].trim();
+            if (!key || key.includes('#'))
+                return null;
+        }
+    }
+    const restOffset = indent.length + match[0].length;
+    return { indent, key, rest: line.slice(restOffset), restOffset };
+}
+function parseWorkspaceListLine(line) {
+    const match = /^([ \t]+)-[ \t]+(.+)$/.exec(line);
+    if (!match)
+        return null;
+    const scalar = parseWorkspaceStringScalar(match[2]);
+    return scalar ? { indent: match[1], value: scalar.value } : null;
+}
+function quoteWorkspaceString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function workspaceLineIndent(line) {
+    if (!line.trim() || line.trimStart().startsWith('#'))
+        return null;
+    return /^([ \t]*)/.exec(line)?.[1] ?? '';
+}
+function workspaceBlockAt(lines, keyLineIndex) {
+    const keyLine = lines[keyLineIndex];
+    const key = parseWorkspaceMapLine(keyLine.text);
+    if (!key)
+        throw new Error('pnpm-workspace.yaml contains an unsupported mapping key.');
+    if (key.indent.includes('\t'))
+        throw new Error('pnpm-workspace.yaml managed sections must use spaces for indentation.');
+    let sectionEndIndex = lines.length;
+    for (let index = keyLineIndex + 1; index < lines.length; index += 1) {
+        const indent = workspaceLineIndent(lines[index].text);
+        if (indent !== null && indent.length <= key.indent.length) {
+            sectionEndIndex = index;
+            break;
+        }
+    }
+    return { lines, keyLineIndex, sectionEndIndex, keyLine, key };
+}
+function findTopLevelWorkspaceBlock(content, key) {
+    const lines = sourceLines(content);
+    const matches = lines.flatMap((line, index) => {
+        const parsed = parseWorkspaceMapLine(line.text);
+        return parsed?.indent === '' && parsed.key === key ? [index] : [];
+    });
+    if (matches.length > 1)
+        throw new Error(`pnpm-workspace.yaml contains duplicate top-level ${key} keys.`);
+    return matches.length === 1 ? workspaceBlockAt(lines, matches[0]) : null;
+}
+function appendWorkspaceLines(content, offset, additions) {
+    if (additions.length === 0)
+        return content;
+    const newline = workspaceNewline(content);
+    const leading = offset > 0 && !/(?:\r\n|\n|\r)$/.test(content.slice(0, offset)) ? newline : '';
+    return `${content.slice(0, offset)}${leading}${additions.join(newline)}${newline}${content.slice(offset)}`;
+}
+function appendTopLevelWorkspaceKey(content, key) {
+    return appendWorkspaceLines(content, content.length, [`${key}:`]);
+}
+function requireWorkspaceBlockValue(block, fieldPath) {
+    if (!/^[ \t]*(?:#.*)?$/.test(block.key.rest)) {
+        throw new Error(`Conflict in ${fieldPath}: expected a block value that can be merged safely.`);
+    }
+}
+function mergeWorkspaceListBlock(content, block, desiredValues, fieldPath) {
+    requireWorkspaceBlockValue(block, fieldPath);
+    const existing = new Set();
+    let indent = `${block.key.indent}  `;
+    let insertionOffset = block.keyLine.end;
+    let foundItem = false;
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        const line = block.lines[index];
+        if (workspaceLineIndent(line.text) === null)
+            continue;
+        const parsed = parseWorkspaceListLine(line.text);
+        if (!parsed || parsed.indent.includes('\t') || parsed.indent.length <= block.key.indent.length) {
+            throw new Error(`Conflict in ${fieldPath}: expected a simple block list of strings.`);
+        }
+        if (foundItem && parsed.indent !== indent) {
+            throw new Error(`Conflict in ${fieldPath}: list items must use consistent indentation.`);
+        }
+        foundItem = true;
+        indent = parsed.indent;
+        existing.add(parsed.value);
+        insertionOffset = line.end;
+    }
+    const additions = [...new Set(desiredValues)].filter((value) => !existing.has(value));
+    return appendWorkspaceLines(content, insertionOffset, additions.map((value) => `${indent}- ${quoteWorkspaceString(value)}`));
+}
+function ensureTopLevelWorkspaceBlock(content, key) {
+    const existing = findTopLevelWorkspaceBlock(content, key);
+    if (existing)
+        return { content, block: existing };
+    const appended = appendTopLevelWorkspaceKey(content, key);
+    return { content: appended, block: findTopLevelWorkspaceBlock(appended, key) };
+}
+function mergeTopLevelWorkspaceList(content, key, desiredValues) {
+    const ensured = ensureTopLevelWorkspaceBlock(content, key);
+    return mergeWorkspaceListBlock(ensured.content, ensured.block, desiredValues, `pnpm-workspace.yaml ${key}`);
+}
+function mergeWorkspaceMapBlock(content, block, desiredValues, fieldPath, allowGeneratedUpdates) {
+    requireWorkspaceBlockValue(block, fieldPath);
+    const entries = new Map();
+    let indent = `${block.key.indent}  `;
+    let insertionOffset = block.keyLine.end;
+    let foundEntry = false;
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        const line = block.lines[index];
+        if (workspaceLineIndent(line.text) === null)
+            continue;
+        const parsed = parseWorkspaceMapLine(line.text);
+        if (!parsed || parsed.indent.includes('\t') || parsed.indent.length <= block.key.indent.length) {
+            throw new Error(`Conflict in ${fieldPath}: expected a simple string-to-string mapping.`);
+        }
+        if (foundEntry && parsed.indent !== indent) {
+            throw new Error(`Conflict in ${fieldPath}: mapping entries must use consistent indentation.`);
+        }
+        const scalar = parseWorkspaceStringScalar(parsed.rest);
+        if (!scalar)
+            throw new Error(`Conflict in ${fieldPath}: mapping values must be strings.`);
+        if (entries.has(parsed.key))
+            throw new Error(`Conflict in ${fieldPath}: duplicate mapping entry ${parsed.key}.`);
+        foundEntry = true;
+        indent = parsed.indent;
+        insertionOffset = line.end;
+        entries.set(parsed.key, { line, parsed, scalar });
+    }
+    const additions = [];
+    const replacements = [];
+    for (const [key, desiredValue] of Object.entries(desiredValues)) {
+        const existing = entries.get(key);
+        if (!existing) {
+            additions.push(`${indent}${quoteWorkspaceString(key)}: ${quoteWorkspaceString(desiredValue)}`);
+            continue;
+        }
+        if (existing.scalar.value === desiredValue)
+            continue;
+        if (!allowGeneratedUpdates) {
+            throw new Error(`Conflict in ${fieldPath}: mapping entry ${key} differs from the generated value.`);
+        }
+        replacements.push({
+            start: existing.line.start + existing.parsed.restOffset + existing.scalar.tokenStart,
+            end: existing.line.start + existing.parsed.restOffset + existing.scalar.tokenEnd,
+            value: quoteWorkspaceString(desiredValue),
+        });
+    }
+    let merged = appendWorkspaceLines(content, insertionOffset, additions);
+    for (const replacement of replacements.sort((left, right) => right.start - left.start)) {
+        merged = `${merged.slice(0, replacement.start)}${replacement.value}${merged.slice(replacement.end)}`;
+    }
+    return merged;
+}
+function mergeTopLevelWorkspaceMap(content, key, desiredValues, allowGeneratedUpdates) {
+    const ensured = ensureTopLevelWorkspaceBlock(content, key);
+    return mergeWorkspaceMapBlock(ensured.content, ensured.block, desiredValues, `pnpm-workspace.yaml ${key}`, allowGeneratedUpdates);
+}
+function directChildIndent(block, fieldPath) {
+    let childIndent = null;
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        const indent = workspaceLineIndent(block.lines[index].text);
+        if (indent === null)
+            continue;
+        if (indent.includes('\t') || indent.length <= block.key.indent.length) {
+            throw new Error(`Conflict in ${fieldPath}: expected an indented mapping.`);
+        }
+        if (childIndent === null || indent.length < childIndent.length)
+            childIndent = indent;
+    }
+    return childIndent ?? `${block.key.indent}  `;
+}
+function findDirectWorkspaceBlock(parent, key, fieldPath) {
+    const childIndent = directChildIndent(parent, fieldPath);
+    const matches = [];
+    for (let index = parent.keyLineIndex + 1; index < parent.sectionEndIndex; index += 1) {
+        const line = parent.lines[index];
+        const indent = workspaceLineIndent(line.text);
+        if (indent === null || indent.length !== childIndent.length)
+            continue;
+        const parsed = parseWorkspaceMapLine(line.text);
+        if (!parsed || parsed.indent !== childIndent) {
+            throw new Error(`Conflict in ${fieldPath}: expected a mapping of named policies.`);
+        }
+        if (parsed.key === key)
+            matches.push(index);
+    }
+    if (matches.length > 1)
+        throw new Error(`Conflict in ${fieldPath}: duplicate ${key} keys.`);
+    return matches.length === 1 ? workspaceBlockAt(parent.lines, matches[0]) : null;
+}
+function ensureDirectWorkspaceBlock(content, parentKey, key, fieldPath) {
+    let parent = findTopLevelWorkspaceBlock(content, parentKey);
+    if (!parent) {
+        content = appendTopLevelWorkspaceKey(content, parentKey);
+        parent = findTopLevelWorkspaceBlock(content, parentKey);
+    }
+    requireWorkspaceBlockValue(parent, `pnpm-workspace.yaml ${parentKey}`);
+    const existing = findDirectWorkspaceBlock(parent, key, fieldPath);
+    if (existing)
+        return { content, block: existing };
+    const indent = directChildIndent(parent, fieldPath);
+    let insertionOffset = parent.keyLine.end;
+    for (let index = parent.keyLineIndex + 1; index < parent.sectionEndIndex; index += 1) {
+        const line = parent.lines[index];
+        if (workspaceLineIndent(line.text) !== null)
+            insertionOffset = line.end;
+    }
+    content = appendWorkspaceLines(content, insertionOffset, [`${indent}${key}:`]);
+    parent = findTopLevelWorkspaceBlock(content, parentKey);
+    return { content, block: findDirectWorkspaceBlock(parent, key, fieldPath) };
+}
+function applyWorkspaceAutoInstallPeers(content, allowGeneratedUpdates) {
+    const block = findTopLevelWorkspaceBlock(content, 'autoInstallPeers');
+    if (!block) {
+        const newline = workspaceNewline(content);
+        const separator = content.length > 0 && !/(?:\r\n|\n|\r)$/.test(content) ? newline : '';
+        return `${content}${separator}autoInstallPeers: false${newline}`;
+    }
+    const scalar = /^([ \t]*)(true|false)([ \t]*(?:#.*)?)$/i.exec(block.key.rest);
+    if (!scalar)
+        throw new Error('Conflict in pnpm-workspace.yaml: autoInstallPeers must be the boolean false.');
+    for (let index = block.keyLineIndex + 1; index < block.sectionEndIndex; index += 1) {
+        if (workspaceLineIndent(block.lines[index].text) !== null) {
+            throw new Error('Conflict in pnpm-workspace.yaml: autoInstallPeers must be a scalar boolean.');
+        }
+    }
+    if (scalar[2].toLowerCase() === 'false')
+        return content;
+    if (!allowGeneratedUpdates) {
+        throw new Error('Conflict in pnpm-workspace.yaml: autoInstallPeers must be false to avoid unsafe optional peer resolution.');
+    }
+    const start = block.keyLine.start + block.key.restOffset + scalar[1].length;
+    return `${content.slice(0, start)}false${content.slice(start + scalar[2].length)}`;
+}
+function applyWorkspacePolicy(content, policy, allowGeneratedUpdates) {
+    let merged = applyWorkspaceAutoInstallPeers(content, allowGeneratedUpdates);
+    merged = mergeTopLevelWorkspaceMap(merged, 'overrides', policy.overrides, allowGeneratedUpdates);
+    merged = mergeTopLevelWorkspaceList(merged, 'onlyBuiltDependencies', policy.onlyBuiltDependencies);
+    merged = mergeTopLevelWorkspaceList(merged, 'ignoredBuiltDependencies', policy.ignoredBuiltDependencies);
+    const ignoreMissing = ensureDirectWorkspaceBlock(merged, 'peerDependencyRules', 'ignoreMissing', 'pnpm-workspace.yaml peerDependencyRules');
+    merged = mergeWorkspaceListBlock(ignoreMissing.content, ignoreMissing.block, policy.peerDependencyRules.ignoreMissing, 'pnpm-workspace.yaml peerDependencyRules.ignoreMissing');
+    const allowedVersions = ensureDirectWorkspaceBlock(merged, 'peerDependencyRules', 'allowedVersions', 'pnpm-workspace.yaml peerDependencyRules');
+    return mergeWorkspaceMapBlock(allowedVersions.content, allowedVersions.block, policy.peerDependencyRules.allowedVersions, 'pnpm-workspace.yaml peerDependencyRules.allowedVersions', allowGeneratedUpdates);
+}
+export function mergeWorkspaceFile(root, desiredPackages, policy, allowGeneratedUpdates) {
+    const filePath = path.join(root, 'pnpm-workspace.yaml');
+    const current = pathEntryExists(filePath) ? readFileSync(filePath, 'utf8') : '';
+    let merged = mergeTopLevelWorkspaceList(current, 'packages', desiredPackages);
+    merged = applyWorkspacePolicy(merged, policy, allowGeneratedUpdates);
+    if (merged !== current || !pathEntryExists(filePath))
+        writeFile(filePath, merged);
+}

package/docs/conventions.md

@@ -0,0 +1,89 @@
+# Anhedral generated-project conventions
+
+Anhedral is a deterministic stack generator. These conventions describe the readable workspace it produces; they are not a new application framework or runtime API.
+
+## Core rule
+
+Use the underlying tool's normal programming model. Anhedral decides where integrations meet and generates safe defaults, but developers write ordinary Next.js, Expo Router, Fastify, Drizzle, Electron, and WXT code.
+
+## Source ownership
+
+```text
+apps/       deployable framework applications
+packages/   client-safe or server-shared TypeScript packages
+docs/       generated stack and development guidance
+```
+
+- `apps/web`: Next.js App Router pages, layouts, components, hooks, and web utilities.
+- `apps/mobile`: Expo Router screens, layouts, native components, and hooks.
+- `apps/api`: Fastify routes, services, plugins, provider clients, and server environment validation.
+- `apps/desktop`: Electron main/preload code and sandboxed React renderer code.
+- `apps/extension`: WXT entrypoints, extension components, background logic, and content scripts.
+- `packages/contracts`: Zod schemas for data crossing HTTP boundaries.
+- `packages/api-client`: client-safe HTTP behavior shared across frontends.
+- `packages/db`: Drizzle schema, database access, and reviewed SQL migrations.
+- `packages/realtime`: client-safe Ably subscription behavior when selected.
+
+## End-to-end feature flow
+
+```text
+Zod contract
+    -> Drizzle schema/query or server service
+    -> Fastify route
+    -> shared API client
+    -> Next.js / Expo / Electron / WXT UI
+```
+
+Routes stay thin. They authenticate, validate, call a service, and return a declared contract. Business behavior and provider SDK calls live in server services. Frontends never import API services, database connections, or server environment modules.
+
+## Database
+
+Database-enabled projects use managed Neon Postgres. Anhedral does not generate local Postgres, Docker Compose, or an embedded database substitute.
+
+1. Edit `packages/db/src/schema.ts`.
+2. Run `pnpm db:generate`.
+3. Review and commit generated SQL and metadata.
+4. Run `pnpm verify:db`.
+5. Apply with `pnpm db:migrate` against the intended Neon branch or project.
+
+Schema generation must not happen during an application build. Migrations are reviewed release artifacts.
+
+## Authentication and secrets
+
+Clerk owns identity and sessions. The API derives identity from a verified server session and never trusts a client-supplied user ID. Only variables with a framework's explicit public prefix may enter client bundles. Database, Clerk secret, R2, RevenueCat, Ably, cron, and provider credentials remain server-only.
+
+## UI
+
+DOM clients use source-owned shadcn/ui components. Expo uses React Native Reusables with the selected NativeWind or Uniwind configuration.
+
+```sh
+anhedral ui add button dialog
+anhedral ui add data-table --target web
+```
+
+Generated UI files are application source and can be customized. Preserve accessibility, keyboard/focus behavior, and platform conventions.
+
+## Naming
+
+- Directories and source files use lowercase kebab-case.
+- React component filenames use kebab-case and export PascalCase components.
+- Hooks start with `use-`.
+- Framework-required entrypoint names stay unchanged.
+- Shared packages use the `@shared/<name>` namespace.
+
+## Structural changes
+
+Run `anhedral doctor` before changing generated structure. Preview new modules or UI with `--dry-run`. Anhedral refuses managed-file drift, symlinks, and unowned collisions instead of overwriting source.
+
+Application product files are developer-owned. `README.md` and `PRODUCTION.md` become user-owned after initialization. Root configuration is mergeable. Integration substrate and generated guidance are recorded in `anhedral.json`.
+
+## Verification
+
+Run the smallest relevant package check while iterating, then the generated root verification before handoff:
+
+```sh
+pnpm typecheck
+pnpm verify
+pnpm build
+anhedral doctor
+```