proteum 2.2.6 → 2.2.8

package/cli/compiler/artifacts/services.ts

@@ -711,6 +711,68 @@ ${classMembers.join('\n')}
     };
 };
 
+const isNamespaceImportDeclaration = (statement: ts.ImportDeclaration) =>
+    statement.importClause?.namedBindings !== undefined && ts.isNamespaceImport(statement.importClause.namedBindings);
+
+const isClientServerStubSupportStatement = (statement: ts.Statement, appClassIdentifier: string) => {
+    if (ts.isTypeAliasDeclaration(statement)) {
+        return !new Set([
+            `${appClassIdentifier}Disks`,
+            `${appClassIdentifier}Router`,
+            `${appClassIdentifier}RouterPlugins`,
+        ]).has(statement.name.text);
+    }
+
+    return ts.isInterfaceDeclaration(statement) || ts.isModuleDeclaration(statement);
+};
+
+const createClientServerIndexDeclaration = (rootServices: TParsedService[]) => {
+    const sourceFile = createSourceFile(getAppServerEntryFilepath());
+    const appClass = getDefaultExportClassDeclaration(sourceFile);
+    const serviceTypesByRegisteredName = new Map(
+        rootServices.map((service) => [service.registeredName, `import("${service.importPath}").default`] as const),
+    );
+
+    const imports = sourceFile.statements
+        .filter((statement): statement is ts.ImportDeclaration => ts.isImportDeclaration(statement))
+        .filter((statement) => !isNamespaceImportDeclaration(statement))
+        .map((statement) => statement.getText(sourceFile));
+    const supportStatements = sourceFile.statements
+        .slice(0, sourceFile.statements.indexOf(appClass))
+        .filter((statement) => isClientServerStubSupportStatement(statement, app.identity.identifier))
+        .map((statement) => statement.getText(sourceFile));
+    const heritageClauses = appClass.heritageClauses?.map((clause) => clause.getText(sourceFile)).join(' ');
+    const properties = appClass.members
+        .filter((member): member is ts.PropertyDeclaration => ts.isPropertyDeclaration(member))
+        .filter((member) => !isPrivateOrProtectedInstanceMember(member))
+        .map((property) => {
+            const propertyName = getPropertyNameText(property.name);
+            if (!propertyName) return undefined;
+
+            const propertyType =
+                propertyName === 'Disks'
+                    ? 'object'
+                    : propertyName === 'Router'
+                      ? `${app.identity.identifier}Router`
+                      : property.type?.getText(sourceFile) || serviceTypesByRegisteredName.get(propertyName);
+            if (!propertyType) return undefined;
+
+            return `    public ${propertyName}: ${propertyType};`;
+        })
+        .filter((property): property is string => property !== undefined);
+
+    return `${imports.join('\n')}
+
+${supportStatements.join('\n\n')}
+
+type ${app.identity.identifier}Router = Router<${app.identity.identifier}>;
+
+export default class ${app.identity.identifier}${heritageClauses ? ` ${heritageClauses}` : ''} {
+${properties.join('\n')}
+}
+`;
+};
+
 const resolveManifestService = (service: TParsedService, parent: string): TProteumManifestService => ({
     kind: 'service',
     registeredName: service.registeredName,
@@ -730,6 +792,11 @@ export const generateServiceArtifacts = () => {
     const routerPluginServices = routerPlugins.map((service) => resolveManifestService(service, 'Router.plugins'));
     const commandServiceStubs = createCommandServiceStubDeclarations(rootServices);
 
+    writeIfChanged(
+        path.join(app.paths.client.generated, 'server-index.d.ts'),
+        createClientServerIndexDeclaration(rootServices),
+    );
+
     writeIfChanged(
         path.join(app.paths.client.generated, 'services.d.ts'),
         `declare type ${appClassIdentifier} = import("@/server/index").default;
@@ -737,18 +804,9 @@ export const generateServiceArtifacts = () => {
 declare module "@app" {
 
     import { ${appClassIdentifier} as ${appClassIdentifier}Client } from "@/client";
-    import ${appClassIdentifier}Server from "@/server/index";
   
     export const Router: ${appClassIdentifier}Client['Router'];
 
-    ${rootServices
-        .map((service) =>
-            service.registeredName !== 'Router'
-                ? `export const ${service.registeredName}: ${appClassIdentifier}Server["${service.registeredName}"];`
-                : '',
-        )
-        .join('\n')}
-
 }
     
 declare module '@models/types' {
@@ -894,26 +952,6 @@ declare module "@app" {
     export = ServerServices
 }
 
-declare module '@server/app' {
-
-    import { Application } from "@server/app";
-    import { Environment } from "@server/app";
-    import { ServicesContainer } from "@server/app/service/container";
-
-    abstract class ApplicationWithServices extends Application<
-        ServicesContainer<InstalledServices>
-    > {}
-
-    export interface Exported {
-        Application: typeof ApplicationWithServices,
-        Environment: Environment,
-    }
-
-    const foo: Exported;
-
-    export = foo;
-}
-
 declare module '@common/errors' {
         
     export * from '@common/errors/index';

package/cli/presentation/commands.ts

@@ -113,22 +113,22 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure Proteum-managed instruction stubs for a standalone app or monorepo app root.',
+        summary: 'Interactively configure tracked Proteum instruction files for a standalone app or monorepo app root.',
         usage: 'proteum configure agents',
         bestFor:
-            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write instruction files implicitly.',
+            'Creating or switching the tracked instruction layout intentionally while keeping Proteum-owned instructions embedded in managed sections.',
         examples: [
             {
-                description: 'Configure instruction stubs for the current standalone app',
+                description: 'Configure instruction files for the current standalone app',
                 command: 'proteum configure agents',
             },
         ],
         notes: [
-            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` stub.',
-            'Standalone mode writes the full app-root instruction set into the current Proteum app root.',
-            'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and switches the current app root `AGENTS.md` to the app-root addendum.',
-            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed stub.',
-            'Declined non-managed paths are left untouched; Proteum still creates missing stubs and updates stubs or symlinks it already manages.',
+            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` file.',
+            'Standalone mode writes tracked instruction files into the current Proteum app root.',
+            'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and the app-root instruction files into the current Proteum app root.',
+            'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
+            'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],
         status: 'experimental',
     },
@@ -191,7 +191,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'Use `--cwd` when the target Proteum app lives in another worktree or checkout and you do not want to `cd` first.',
             'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
-            'Before the interactive dev loop starts, Proteum offers to launch `proteum configure agents` when the app root is missing `AGENTS.md`.',
+            'Before the dev loop starts, Proteum ensures tracked instruction files contain the current managed `# Proteum Instructions` section.',
             'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
             '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
             '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('When the app root is missing `AGENTS.md`, the interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/scaffold/index.ts

@@ -5,7 +5,6 @@ import { UsageError } from 'clipanion';
 
 import cli from '..';
 import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
-import { renderProjectInstructionGitignoreBlock } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
     createClientTsconfigTemplate,
@@ -656,9 +655,7 @@ const createInitFilePlans = ({ appRoot, config }: { appRoot: string; config: TSc
     },
     {
         relativePath: '.gitignore',
-        content: createGitignoreTemplate({
-            projectInstructionGitignoreBlock: renderProjectInstructionGitignoreBlock({ coreRoot: cli.paths.core.root }),
-        }),
+        content: createGitignoreTemplate(),
     },
     {
         relativePath: 'eslint.config.mjs',
@@ -727,7 +724,7 @@ export const runInitScaffold = async () => {
               ? 'Run `npm run dev` in the new app directory.'
               : 'Run `npm install`, then `npm run dev` in the new app directory.',
     );
-    result.nextSteps.push('Run `proteum configure agents` when you want Proteum-managed instruction stubs.');
+    result.nextSteps.push('Run `proteum configure agents` when you want tracked Proteum instruction files.');
     result.nextSteps.push('Use `proteum create page|controller|command|route|service ...` to add app artifacts.');
 
     printResult(result, createInitSummary(result, config));

package/cli/scaffold/templates.ts

@@ -191,6 +191,7 @@ export const createClientTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
             "@server/*": [${JSON.stringify(paths.frameworkServer)}],
 
             "@/client/context": ["./.proteum/client/context.ts"],
+            "@/server/index": ["./.proteum/client/server-index.d.ts"],
             "@generated/client/*": ["./.proteum/client/*"],
             "@generated/common/*": ["./.proteum/common/*"],
             "@generated/server/*": ["./.proteum/server/*"],
@@ -207,8 +208,7 @@ export const createClientTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
         ".",
         "../var/typings",
         ${JSON.stringify(paths.frameworkTypesGlobal)},
-        "../.proteum/client/services.d.ts",
-        "../server/index.ts"
+        "../.proteum/client/services.d.ts"
     ]
 }
 `;
@@ -228,7 +228,6 @@ export const createServerTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
             "@common/*": [${JSON.stringify(paths.frameworkCommon)}],
             "@server/*": [${JSON.stringify(paths.frameworkServer)}],
 
-            "@/client/context": ["./.proteum/client/context.ts"],
             "@generated/client/*": ["./.proteum/client/*"],
             "@generated/common/*": ["./.proteum/common/*"],
             "@generated/server/*": ["./.proteum/server/*"],
@@ -253,11 +252,7 @@ export const createServerTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
 }
 `;
 
-export const createGitignoreTemplate = ({
-    projectInstructionGitignoreBlock,
-}: {
-    projectInstructionGitignoreBlock: string;
-}) => `node_modules
+export const createGitignoreTemplate = () => `node_modules
 /.proteum
 /.cache
 /bin
@@ -265,8 +260,6 @@ export const createGitignoreTemplate = ({
 /var
 /proteum.connected.json
 .env
-
-${projectInstructionGitignoreBlock}
 `;
 
 export const createEnvTemplate = ({ port, url }: { port: number; url: string }) => `ENV_NAME=local