@tanstack/cta-engine 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tanstack/cta-engine
 
+## 0.49.0
+
+### Minor Changes
+
+- Added categories, colors, exclusive tagging, addon file attribution utils, and railway addon ([#303](https://github.com/TanStack/create-tsrouter-app/pull/303))
+
 ## 0.48.0
 
 ### Minor Changes

package/dist/attribution.js

@@ -0,0 +1,162 @@
+function normalizePath(path) {
+    let p = path.startsWith('./') ? path.slice(2) : path;
+    p = p.replace(/\.ejs$/, '').replace(/_dot_/g, '.');
+    const match = p.match(/^(.+\/)?__([^_]+)__(.+)$/);
+    return match ? (match[1] || '') + match[3] : p;
+}
+async function getFileProvenance(filePath, framework, addOns, starter) {
+    const target = filePath.startsWith('./') ? filePath.slice(2) : filePath;
+    if (starter) {
+        const files = await starter.getFiles();
+        if (files.some((f) => normalizePath(f) === target)) {
+            return {
+                source: 'starter',
+                sourceId: starter.id,
+                sourceName: starter.name,
+            };
+        }
+    }
+    // Order add-ons by type then phase (matches writeFiles order), check in reverse
+    const typeOrder = ['add-on', 'example', 'toolchain', 'deployment'];
+    const phaseOrder = ['setup', 'add-on', 'example'];
+    const ordered = typeOrder.flatMap((type) => phaseOrder.flatMap((phase) => addOns.filter((a) => a.phase === phase && a.type === type)));
+    for (let i = ordered.length - 1; i >= 0; i--) {
+        const files = await ordered[i].getFiles();
+        if (files.some((f) => normalizePath(f) === target)) {
+            return {
+                source: 'add-on',
+                sourceId: ordered[i].id,
+                sourceName: ordered[i].name,
+            };
+        }
+    }
+    const frameworkFiles = await framework.getFiles();
+    if (frameworkFiles.some((f) => normalizePath(f) === target)) {
+        return {
+            source: 'framework',
+            sourceId: framework.id,
+            sourceName: framework.name,
+        };
+    }
+    return null;
+}
+// Build injection patterns from integrations (for source files)
+function integrationInjections(int) {
+    const source = { sourceId: int._sourceId, sourceName: int._sourceName };
+    const injections = [];
+    const appliesTo = (path) => {
+        if (int.type === 'vite-plugin')
+            return path.includes('vite.config');
+        if (int.type === 'provider' ||
+            int.type === 'root-provider' ||
+            int.type === 'devtools') {
+            return path.includes('__root') || path.includes('root.tsx');
+        }
+        return false;
+    };
+    if (int.import) {
+        const prefix = int.import.split(' from ')[0];
+        injections.push({
+            matches: (line) => line.includes(prefix),
+            appliesTo,
+            source,
+        });
+    }
+    const code = int.code || int.jsName;
+    if (code) {
+        injections.push({
+            matches: (line) => line.includes(code),
+            appliesTo,
+            source,
+        });
+    }
+    return injections;
+}
+// Build injection pattern from a dependency (for package.json)
+function dependencyInjection(dep) {
+    return {
+        matches: (line) => line.includes(`"${dep.name}"`),
+        appliesTo: (path) => path.endsWith('package.json'),
+        source: { sourceId: dep.sourceId, sourceName: dep.sourceName },
+    };
+}
+export async function computeAttribution(input) {
+    const { framework, chosenAddOns, starter, files } = input;
+    // Collect integrations tagged with source
+    const integrations = chosenAddOns.flatMap((addOn) => (addOn.integrations || []).map((int) => ({
+        ...int,
+        _sourceId: addOn.id,
+        _sourceName: addOn.name,
+    })));
+    // Collect dependencies from add-ons (from packageAdditions or packageTemplate)
+    const dependencies = chosenAddOns.flatMap((addOn) => {
+        const result = [];
+        const source = { sourceId: addOn.id, sourceName: addOn.name };
+        const addDeps = (deps, type) => {
+            if (!deps)
+                return;
+            for (const [name, version] of Object.entries(deps)) {
+                if (typeof version === 'string') {
+                    result.push({ name, version, type, ...source });
+                }
+            }
+        };
+        // From static package.json
+        addDeps(addOn.packageAdditions?.dependencies, 'dependency');
+        addDeps(addOn.packageAdditions?.devDependencies, 'devDependency');
+        // From package.json.ejs template (strip EJS tags and parse)
+        if (addOn.packageTemplate) {
+            try {
+                const tmpl = JSON.parse(addOn.packageTemplate.replace(/"[^"]*<%[^%]*%>[^"]*"/g, '""'));
+                addDeps(tmpl.dependencies, 'dependency');
+                addDeps(tmpl.devDependencies, 'devDependency');
+            }
+            catch { }
+        }
+        return result;
+    });
+    // Build unified injection patterns from both integrations and dependencies
+    const injections = [
+        ...integrations.flatMap(integrationInjections),
+        ...dependencies.map(dependencyInjection),
+    ];
+    const attributedFiles = {};
+    for (const [filePath, content] of Object.entries(files)) {
+        const provenance = await getFileProvenance(filePath, framework, chosenAddOns, starter);
+        if (!provenance)
+            continue;
+        const lines = content.split('\n');
+        const relevant = injections.filter((inj) => inj.appliesTo(filePath));
+        // Find injected lines
+        const injectedLines = new Map();
+        for (const inj of relevant) {
+            lines.forEach((line, i) => {
+                if (inj.matches(line) && !injectedLines.has(i + 1)) {
+                    injectedLines.set(i + 1, inj.source);
+                }
+            });
+        }
+        attributedFiles[filePath] = {
+            content,
+            provenance,
+            lineAttributions: lines.map((_, i) => {
+                const lineNum = i + 1;
+                const inj = injectedLines.get(lineNum);
+                return inj
+                    ? {
+                        line: lineNum,
+                        sourceId: inj.sourceId,
+                        sourceName: inj.sourceName,
+                        type: 'injected',
+                    }
+                    : {
+                        line: lineNum,
+                        sourceId: provenance.sourceId,
+                        sourceName: provenance.sourceName,
+                        type: 'original',
+                    };
+            }),
+        };
+    }
+    return { attributedFiles, dependencies };
+}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { createApp } from './create-app.js';
+export { computeAttribution } from './attribution.js';
 export { addToApp } from './add-to-app.js';
-export { finalizeAddOns, getAllAddOns, populateAddOnOptionsDefaults } from './add-ons.js';
+export { finalizeAddOns, getAllAddOns, populateAddOnOptionsDefaults, } from './add-ons.js';
 export { loadRemoteAddOn } from './custom-add-ons/add-on.js';
 export { loadStarter } from './custom-add-ons/starter.js';
 export { createMemoryEnvironment, createDefaultEnvironment, } from './environment.js';

package/dist/template-file.js

@@ -26,11 +26,16 @@ export function createTemplateFile(environment, options) {
             this.name = 'IgnoreFileError';
         }
     }
+    // Collect integrations and tag them with source add-on for attribution
     const integrations = [];
     for (const addOn of options.chosenAddOns) {
         if (addOn.integrations) {
             for (const integration of addOn.integrations) {
-                integrations.push(integration);
+                integrations.push({
+                    ...integration,
+                    _sourceId: addOn.id,
+                    _sourceName: addOn.name,
+                });
             }
         }
     }

package/dist/types/attribution.d.ts

@@ -0,0 +1,12 @@
+import type { AddOn, AttributedFile, DependencyAttribution, Framework, Starter } from './types.js';
+export interface AttributionInput {
+    framework: Framework;
+    chosenAddOns: Array<AddOn>;
+    starter?: Starter;
+    files: Record<string, string>;
+}
+export interface AttributionOutput {
+    attributedFiles: Record<string, AttributedFile>;
+    dependencies: Array<DependencyAttribution>;
+}
+export declare function computeAttribution(input: AttributionInput): Promise<AttributionOutput>;

package/dist/types/custom-add-ons/add-on.d.ts

@@ -39,6 +39,9 @@ export declare function generateProject(persistedOptions: PersistedOptions): Pro
         link?: string | undefined;
         license?: string | undefined;
         warning?: string | undefined;
+        category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+        exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+        color?: string | undefined;
         priority?: number | undefined;
         routes?: {
             path: string;
@@ -67,14 +70,7 @@ export declare function generateProject(persistedOptions: PersistedOptions): Pro
         }[] | undefined;
         readme?: string | undefined;
     };
-    output: {
-        files: Record<string, string>;
-        deletedFiles: Array<string>;
-        commands: Array<{
-            command: string;
-            args: Array<string>;
-        }>;
-    };
+    output: import("../environment.js").MemoryEnvironmentOutput;
 }>;
 export declare function buildAssetsDirectory(output: {
     files: Record<string, string>;

package/dist/types/custom-add-ons/shared.d.ts

@@ -3,13 +3,6 @@ import type { PersistedOptions } from '../config-file.js';
 export declare function createPackageAdditions(originalPackageJson: Record<string, any>, currentPackageJson: Record<string, any>): Record<string, any>;
 export declare function createAppOptionsFromPersisted(json: PersistedOptions): Promise<Options>;
 export declare function createSerializedOptionsFromPersisted(json: PersistedOptions): SerializedOptions;
-export declare function runCreateApp(options: Required<Options>): Promise<{
-    files: Record<string, string>;
-    deletedFiles: Array<string>;
-    commands: Array<{
-        command: string;
-        args: Array<string>;
-    }>;
-}>;
+export declare function runCreateApp(options: Required<Options>): Promise<import("../environment.js").MemoryEnvironmentOutput>;
 export declare function compareFilesRecursively(path: string, ignore: (filePath: string) => boolean, original: Record<string, string>, changedFiles: Record<string, string>): Promise<void>;
 export declare function readCurrentProjectOptions(environment: Environment): Promise<PersistedOptions>;

package/dist/types/environment.d.ts

@@ -1,13 +1,14 @@
 import type { Environment } from './types.js';
+export interface MemoryEnvironmentOutput {
+    files: Record<string, string>;
+    deletedFiles: Array<string>;
+    commands: Array<{
+        command: string;
+        args: Array<string>;
+    }>;
+}
 export declare function createDefaultEnvironment(): Environment;
 export declare function createMemoryEnvironment(returnPathsRelativeTo?: string): {
     environment: Environment;
-    output: {
-        files: Record<string, string>;
-        deletedFiles: Array<string>;
-        commands: Array<{
-            command: string;
-            args: Array<string>;
-        }>;
-    };
+    output: MemoryEnvironmentOutput;
 };

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export { createApp } from './create-app.js';
+export { computeAttribution } from './attribution.js';
 export { addToApp } from './add-to-app.js';
-export { finalizeAddOns, getAllAddOns, populateAddOnOptionsDefaults } from './add-ons.js';
+export { finalizeAddOns, getAllAddOns, populateAddOnOptionsDefaults, } from './add-ons.js';
 export { loadRemoteAddOn } from './custom-add-ons/add-on.js';
 export { loadStarter } from './custom-add-ons/starter.js';
 export { createMemoryEnvironment, createDefaultEnvironment, } from './environment.js';
@@ -16,6 +17,8 @@ export { createAppOptionsFromPersisted, createSerializedOptionsFromPersisted, }
 export { createSerializedOptions } from './options.js';
 export { getRawRegistry, getRegistry, getRegistryAddOns, getRegistryStarters, } from './registry.js';
 export { StarterCompiledSchema, StatusEvent, StatusStepType, StopEvent, AddOnCompiledSchema, AddOnInfoSchema, IntegrationSchema, } from './types.js';
-export type { AddOn, AddOnOption, AddOnOptions, AddOnSelectOption, AddOnSelection, Environment, FileBundleHandler, Framework, FrameworkDefinition, Options, SerializedOptions, Starter, StarterCompiled, } from './types.js';
+export type { AddOn, AddOnOption, AddOnOptions, AddOnSelectOption, AddOnSelection, Environment, FileBundleHandler, Framework, FrameworkDefinition, Options, SerializedOptions, Starter, StarterCompiled, LineAttribution, FileProvenance, AttributedFile, DependencyAttribution, } from './types.js';
+export type { AttributionInput, AttributionOutput } from './attribution.js';
+export type { MemoryEnvironmentOutput } from './environment.js';
 export type { PersistedOptions } from './config-file.js';
 export type { PackageManager } from './package-manager.js';

package/dist/types/types.d.ts

@@ -114,6 +114,9 @@ export declare const AddOnBaseSchema: z.ZodObject<{
     warning: z.ZodOptional<z.ZodString>;
     tailwind: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     type: z.ZodEnum<["add-on", "example", "starter", "toolchain", "deployment"]>;
+    category: z.ZodOptional<z.ZodEnum<["tanstack", "database", "orm", "auth", "deploy", "styling", "monitoring", "cms", "api", "i18n", "tooling", "other"]>>;
+    exclusive: z.ZodOptional<z.ZodArray<z.ZodEnum<["orm", "auth", "deploy", "database", "linter"]>, "many">>;
+    color: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodNumber>;
     command: z.ZodOptional<z.ZodObject<{
         command: z.ZodString;
@@ -222,6 +225,9 @@ export declare const AddOnBaseSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -267,6 +273,9 @@ export declare const AddOnBaseSchema: z.ZodObject<{
     license?: string | undefined;
     warning?: string | undefined;
     tailwind?: boolean | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -297,6 +306,9 @@ export declare const StarterSchema: z.ZodObject<{
     license: z.ZodOptional<z.ZodString>;
     warning: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<["add-on", "example", "starter", "toolchain", "deployment"]>;
+    category: z.ZodOptional<z.ZodEnum<["tanstack", "database", "orm", "auth", "deploy", "styling", "monitoring", "cms", "api", "i18n", "tooling", "other"]>>;
+    exclusive: z.ZodOptional<z.ZodArray<z.ZodEnum<["orm", "auth", "deploy", "database", "linter"]>, "many">>;
+    color: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodNumber>;
     command: z.ZodOptional<z.ZodObject<{
         command: z.ZodString;
@@ -414,6 +426,9 @@ export declare const StarterSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -463,6 +478,9 @@ export declare const StarterSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -494,6 +512,9 @@ export declare const StarterCompiledSchema: z.ZodObject<{
     license: z.ZodOptional<z.ZodString>;
     warning: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<["add-on", "example", "starter", "toolchain", "deployment"]>;
+    category: z.ZodOptional<z.ZodEnum<["tanstack", "database", "orm", "auth", "deploy", "styling", "monitoring", "cms", "api", "i18n", "tooling", "other"]>>;
+    exclusive: z.ZodOptional<z.ZodArray<z.ZodEnum<["orm", "auth", "deploy", "database", "linter"]>, "many">>;
+    color: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodNumber>;
     command: z.ZodOptional<z.ZodObject<{
         command: z.ZodString;
@@ -616,6 +637,9 @@ export declare const StarterCompiledSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -667,6 +691,9 @@ export declare const StarterCompiledSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -718,6 +745,9 @@ export declare const AddOnInfoSchema: z.ZodObject<{
     warning: z.ZodOptional<z.ZodString>;
     tailwind: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     type: z.ZodEnum<["add-on", "example", "starter", "toolchain", "deployment"]>;
+    category: z.ZodOptional<z.ZodEnum<["tanstack", "database", "orm", "auth", "deploy", "styling", "monitoring", "cms", "api", "i18n", "tooling", "other"]>>;
+    exclusive: z.ZodOptional<z.ZodArray<z.ZodEnum<["orm", "auth", "deploy", "database", "linter"]>, "many">>;
+    color: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodNumber>;
     command: z.ZodOptional<z.ZodObject<{
         command: z.ZodString;
@@ -851,6 +881,9 @@ export declare const AddOnInfoSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -906,6 +939,9 @@ export declare const AddOnInfoSchema: z.ZodObject<{
     license?: string | undefined;
     warning?: string | undefined;
     tailwind?: boolean | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -945,6 +981,9 @@ export declare const AddOnCompiledSchema: z.ZodObject<{
     warning: z.ZodOptional<z.ZodString>;
     tailwind: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     type: z.ZodEnum<["add-on", "example", "starter", "toolchain", "deployment"]>;
+    category: z.ZodOptional<z.ZodEnum<["tanstack", "database", "orm", "auth", "deploy", "styling", "monitoring", "cms", "api", "i18n", "tooling", "other"]>>;
+    exclusive: z.ZodOptional<z.ZodArray<z.ZodEnum<["orm", "auth", "deploy", "database", "linter"]>, "many">>;
+    color: z.ZodOptional<z.ZodString>;
     priority: z.ZodOptional<z.ZodNumber>;
     command: z.ZodOptional<z.ZodObject<{
         command: z.ZodString;
@@ -1084,6 +1123,9 @@ export declare const AddOnCompiledSchema: z.ZodObject<{
     link?: string | undefined;
     license?: string | undefined;
     warning?: string | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -1142,6 +1184,9 @@ export declare const AddOnCompiledSchema: z.ZodObject<{
     license?: string | undefined;
     warning?: string | undefined;
     tailwind?: boolean | undefined;
+    category?: "other" | "tanstack" | "database" | "orm" | "auth" | "deploy" | "styling" | "monitoring" | "cms" | "api" | "i18n" | "tooling" | undefined;
+    exclusive?: ("database" | "orm" | "auth" | "deploy" | "linter")[] | undefined;
+    color?: string | undefined;
     priority?: number | undefined;
     routes?: {
         path: string;
@@ -1279,4 +1324,31 @@ type UIEnvironment = {
     confirm: (message: string) => Promise<boolean>;
 };
 export type Environment = ProjectEnvironment & FileEnvironment & UIEnvironment;
+export interface LineAttribution {
+    line: number;
+    sourceId: string;
+    sourceName: string;
+    type: 'original' | 'injected';
+}
+export interface FileProvenance {
+    source: 'framework' | 'add-on' | 'starter';
+    sourceId: string;
+    sourceName: string;
+}
+export interface AttributedFile {
+    content: string;
+    provenance: FileProvenance;
+    lineAttributions: Array<LineAttribution>;
+}
+export interface DependencyAttribution {
+    name: string;
+    version: string;
+    type: 'dependency' | 'devDependency';
+    sourceId: string;
+    sourceName: string;
+}
+export type IntegrationWithSource = Integration & {
+    _sourceId: string;
+    _sourceName: string;
+};
 export {};

package/dist/types.js

@@ -24,6 +24,26 @@ export const AddOnBaseSchema = z.object({
     warning: z.string().optional(),
     tailwind: z.boolean().optional().default(true),
     type: z.enum(['add-on', 'example', 'starter', 'toolchain', 'deployment']),
+    category: z
+        .enum([
+        'tanstack',
+        'database',
+        'orm',
+        'auth',
+        'deploy',
+        'styling',
+        'monitoring',
+        'cms',
+        'api',
+        'i18n',
+        'tooling',
+        'other',
+    ])
+        .optional(),
+    exclusive: z
+        .array(z.enum(['orm', 'auth', 'deploy', 'database', 'linter']))
+        .optional(),
+    color: z.string().optional(),
     priority: z.number().optional(),
     command: z
         .object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cta-engine",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Tanstack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",

package/src/attribution.ts

@@ -0,0 +1,245 @@
+import type {
+  AddOn,
+  AttributedFile,
+  DependencyAttribution,
+  FileProvenance,
+  Framework,
+  Integration,
+  IntegrationWithSource,
+  LineAttribution,
+  Starter,
+} from './types.js'
+
+export interface AttributionInput {
+  framework: Framework
+  chosenAddOns: Array<AddOn>
+  starter?: Starter
+  files: Record<string, string>
+}
+
+export interface AttributionOutput {
+  attributedFiles: Record<string, AttributedFile>
+  dependencies: Array<DependencyAttribution>
+}
+
+type Source = { sourceId: string; sourceName: string }
+
+// A pattern to search for in file content, with its source add-on
+interface Injection {
+  matches: (line: string) => boolean
+  appliesTo: (filePath: string) => boolean
+  source: Source
+}
+
+function normalizePath(path: string): string {
+  let p = path.startsWith('./') ? path.slice(2) : path
+  p = p.replace(/\.ejs$/, '').replace(/_dot_/g, '.')
+  const match = p.match(/^(.+\/)?__([^_]+)__(.+)$/)
+  return match ? (match[1] || '') + match[3] : p
+}
+
+async function getFileProvenance(
+  filePath: string,
+  framework: Framework,
+  addOns: Array<AddOn>,
+  starter?: Starter,
+): Promise<FileProvenance | null> {
+  const target = filePath.startsWith('./') ? filePath.slice(2) : filePath
+
+  if (starter) {
+    const files = await starter.getFiles()
+    if (files.some((f: string) => normalizePath(f) === target)) {
+      return {
+        source: 'starter',
+        sourceId: starter.id,
+        sourceName: starter.name,
+      }
+    }
+  }
+
+  // Order add-ons by type then phase (matches writeFiles order), check in reverse
+  const typeOrder = ['add-on', 'example', 'toolchain', 'deployment']
+  const phaseOrder = ['setup', 'add-on', 'example']
+  const ordered = typeOrder.flatMap((type) =>
+    phaseOrder.flatMap((phase) =>
+      addOns.filter((a) => a.phase === phase && a.type === type),
+    ),
+  )
+
+  for (let i = ordered.length - 1; i >= 0; i--) {
+    const files = await ordered[i].getFiles()
+    if (files.some((f: string) => normalizePath(f) === target)) {
+      return {
+        source: 'add-on',
+        sourceId: ordered[i].id,
+        sourceName: ordered[i].name,
+      }
+    }
+  }
+
+  const frameworkFiles = await framework.getFiles()
+  if (frameworkFiles.some((f: string) => normalizePath(f) === target)) {
+    return {
+      source: 'framework',
+      sourceId: framework.id,
+      sourceName: framework.name,
+    }
+  }
+
+  return null
+}
+
+// Build injection patterns from integrations (for source files)
+function integrationInjections(int: IntegrationWithSource): Array<Injection> {
+  const source = { sourceId: int._sourceId, sourceName: int._sourceName }
+  const injections: Array<Injection> = []
+
+  const appliesTo = (path: string) => {
+    if (int.type === 'vite-plugin') return path.includes('vite.config')
+    if (
+      int.type === 'provider' ||
+      int.type === 'root-provider' ||
+      int.type === 'devtools'
+    ) {
+      return path.includes('__root') || path.includes('root.tsx')
+    }
+    return false
+  }
+
+  if (int.import) {
+    const prefix = int.import.split(' from ')[0]
+    injections.push({
+      matches: (line) => line.includes(prefix),
+      appliesTo,
+      source,
+    })
+  }
+
+  const code = int.code || int.jsName
+  if (code) {
+    injections.push({
+      matches: (line) => line.includes(code),
+      appliesTo,
+      source,
+    })
+  }
+
+  return injections
+}
+
+// Build injection pattern from a dependency (for package.json)
+function dependencyInjection(dep: DependencyAttribution): Injection {
+  return {
+    matches: (line) => line.includes(`"${dep.name}"`),
+    appliesTo: (path) => path.endsWith('package.json'),
+    source: { sourceId: dep.sourceId, sourceName: dep.sourceName },
+  }
+}
+
+export async function computeAttribution(
+  input: AttributionInput,
+): Promise<AttributionOutput> {
+  const { framework, chosenAddOns, starter, files } = input
+
+  // Collect integrations tagged with source
+  const integrations: Array<IntegrationWithSource> = chosenAddOns.flatMap(
+    (addOn) =>
+      (addOn.integrations || []).map((int: Integration) => ({
+        ...int,
+        _sourceId: addOn.id,
+        _sourceName: addOn.name,
+      })),
+  )
+
+  // Collect dependencies from add-ons (from packageAdditions or packageTemplate)
+  const dependencies: Array<DependencyAttribution> = chosenAddOns.flatMap(
+    (addOn) => {
+      const result: Array<DependencyAttribution> = []
+      const source = { sourceId: addOn.id, sourceName: addOn.name }
+
+      const addDeps = (
+        deps: Record<string, unknown> | undefined,
+        type: 'dependency' | 'devDependency',
+      ) => {
+        if (!deps) return
+        for (const [name, version] of Object.entries(deps)) {
+          if (typeof version === 'string') {
+            result.push({ name, version, type, ...source })
+          }
+        }
+      }
+
+      // From static package.json
+      addDeps(addOn.packageAdditions?.dependencies, 'dependency')
+      addDeps(addOn.packageAdditions?.devDependencies, 'devDependency')
+
+      // From package.json.ejs template (strip EJS tags and parse)
+      if (addOn.packageTemplate) {
+        try {
+          const tmpl = JSON.parse(
+            addOn.packageTemplate.replace(/"[^"]*<%[^%]*%>[^"]*"/g, '""'),
+          )
+          addDeps(tmpl.dependencies, 'dependency')
+          addDeps(tmpl.devDependencies, 'devDependency')
+        } catch {}
+      }
+
+      return result
+    },
+  )
+
+  // Build unified injection patterns from both integrations and dependencies
+  const injections: Array<Injection> = [
+    ...integrations.flatMap(integrationInjections),
+    ...dependencies.map(dependencyInjection),
+  ]
+
+  const attributedFiles: Record<string, AttributedFile> = {}
+
+  for (const [filePath, content] of Object.entries(files)) {
+    const provenance = await getFileProvenance(
+      filePath,
+      framework,
+      chosenAddOns,
+      starter,
+    )
+    if (!provenance) continue
+
+    const lines = content.split('\n')
+    const relevant = injections.filter((inj) => inj.appliesTo(filePath))
+
+    // Find injected lines
+    const injectedLines = new Map<number, Source>()
+    for (const inj of relevant) {
+      lines.forEach((line, i) => {
+        if (inj.matches(line) && !injectedLines.has(i + 1)) {
+          injectedLines.set(i + 1, inj.source)
+        }
+      })
+    }
+
+    attributedFiles[filePath] = {
+      content,
+      provenance,
+      lineAttributions: lines.map((_, i): LineAttribution => {
+        const lineNum = i + 1
+        const inj = injectedLines.get(lineNum)
+        return inj
+          ? {
+              line: lineNum,
+              sourceId: inj.sourceId,
+              sourceName: inj.sourceName,
+              type: 'injected',
+            }
+          : {
+              line: lineNum,
+              sourceId: provenance.sourceId,
+              sourceName: provenance.sourceName,
+              type: 'original',
+            }
+      }),
+    }
+  }
+
+  return { attributedFiles, dependencies }
+}

package/src/environment.ts

@@ -21,6 +21,12 @@ import {
 
 import type { Environment } from './types.js'
 
+export interface MemoryEnvironmentOutput {
+  files: Record<string, string>
+  deletedFiles: Array<string>
+  commands: Array<{ command: string; args: Array<string> }>
+}
+
 export function createDefaultEnvironment(): Environment {
   let errors: Array<string> = []
   return {
@@ -46,7 +52,12 @@ export function createDefaultEnvironment(): Environment {
       await mkdir(dirname(path), { recursive: true })
       return writeFile(path, getBinaryFile(base64Contents) as string)
     },
-    execute: async (command: string, args: Array<string>, cwd: string, options?: { inherit?: boolean }) => {
+    execute: async (
+      command: string,
+      args: Array<string>,
+      cwd: string,
+      options?: { inherit?: boolean },
+    ) => {
       try {
         if (options?.inherit) {
           // For commands that should show output directly to the user
@@ -106,14 +117,7 @@ export function createDefaultEnvironment(): Environment {
 export function createMemoryEnvironment(returnPathsRelativeTo: string = '') {
   const environment = createDefaultEnvironment()
 
-  const output: {
-    files: Record<string, string>
-    deletedFiles: Array<string>
-    commands: Array<{
-      command: string
-      args: Array<string>
-    }>
-  } = {
+  const output: MemoryEnvironmentOutput = {
     files: {},
     commands: [],
     deletedFiles: [],

package/src/index.ts

@@ -1,7 +1,12 @@
 export { createApp } from './create-app.js'
+export { computeAttribution } from './attribution.js'
 export { addToApp } from './add-to-app.js'
 
-export { finalizeAddOns, getAllAddOns, populateAddOnOptionsDefaults } from './add-ons.js'
+export {
+  finalizeAddOns,
+  getAllAddOns,
+  populateAddOnOptionsDefaults,
+} from './add-ons.js'
 
 export { loadRemoteAddOn } from './custom-add-ons/add-on.js'
 export { loadStarter } from './custom-add-ons/starter.js'
@@ -85,6 +90,12 @@ export type {
   SerializedOptions,
   Starter,
   StarterCompiled,
+  LineAttribution,
+  FileProvenance,
+  AttributedFile,
+  DependencyAttribution,
 } from './types.js'
+export type { AttributionInput, AttributionOutput } from './attribution.js'
+export type { MemoryEnvironmentOutput } from './environment.js'
 export type { PersistedOptions } from './config-file.js'
 export type { PackageManager } from './package-manager.js'

package/src/template-file.ts

@@ -9,7 +9,13 @@ import {
 } from './package-manager.js'
 import { relativePath } from './file-helpers.js'
 
-import type { AddOn, Environment, Integration, Options } from './types.js'
+import type {
+  AddOn,
+  Environment,
+  Integration,
+  IntegrationWithSource,
+  Options,
+} from './types.js'
 
 function convertDotFilesAndPaths(path: string) {
   return path
@@ -50,11 +56,16 @@ export function createTemplateFile(environment: Environment, options: Options) {
     }
   }
 
-  const integrations: Array<Required<AddOn>['integrations'][number]> = []
+  // Collect integrations and tag them with source add-on for attribution
+  const integrations: Array<IntegrationWithSource> = []
   for (const addOn of options.chosenAddOns) {
     if (addOn.integrations) {
       for (const integration of addOn.integrations) {
-        integrations.push(integration)
+        integrations.push({
+          ...integration,
+          _sourceId: addOn.id,
+          _sourceName: addOn.name,
+        })
       }
     }
   }

package/src/types.ts

@@ -39,6 +39,26 @@ export const AddOnBaseSchema = z.object({
   warning: z.string().optional(),
   tailwind: z.boolean().optional().default(true),
   type: z.enum(['add-on', 'example', 'starter', 'toolchain', 'deployment']),
+  category: z
+    .enum([
+      'tanstack',
+      'database',
+      'orm',
+      'auth',
+      'deploy',
+      'styling',
+      'monitoring',
+      'cms',
+      'api',
+      'i18n',
+      'tooling',
+      'other',
+    ])
+    .optional(),
+  exclusive: z
+    .array(z.enum(['orm', 'auth', 'deploy', 'database', 'linter']))
+    .optional(),
+  color: z.string().optional(),
   priority: z.number().optional(),
   command: z
     .object({
@@ -256,3 +276,37 @@ type UIEnvironment = {
 }
 
 export type Environment = ProjectEnvironment & FileEnvironment & UIEnvironment
+
+// Attribution tracking types for file provenance
+export interface LineAttribution {
+  line: number
+  sourceId: string
+  sourceName: string
+  type: 'original' | 'injected'
+}
+
+export interface FileProvenance {
+  source: 'framework' | 'add-on' | 'starter'
+  sourceId: string
+  sourceName: string
+}
+
+export interface AttributedFile {
+  content: string
+  provenance: FileProvenance
+  lineAttributions: Array<LineAttribution>
+}
+
+export interface DependencyAttribution {
+  name: string
+  version: string
+  type: 'dependency' | 'devDependency'
+  sourceId: string
+  sourceName: string
+}
+
+// Integration with source add-on tracking (used in templates and attribution)
+export type IntegrationWithSource = Integration & {
+  _sourceId: string
+  _sourceName: string
+}