@tanstack/cta-engine 0.48.0 → 0.49.1

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/custom-add-ons/shared.ts

@@ -5,7 +5,7 @@ import { createMemoryEnvironment } from '../environment.js'
 import { finalizeAddOns, populateAddOnOptionsDefaults } from '../add-ons.js'
 import { getFrameworkById } from '../frameworks.js'
 import { readConfigFileFromEnvironment } from '../config-file.js'
-import { readFileHelper } from '../file-helpers.js'
+import { readFileHelper, toCleanPath } from '../file-helpers.js'
 import { loadStarter } from '../custom-add-ons/starter.js'
 
 import type { Environment, Options, SerializedOptions } from '../types.js'
@@ -117,9 +117,10 @@ export async function runCreateApp(options: Required<Options>) {
   })
 
   output.files = Object.fromEntries(
-    Object.entries(output.files).map(([key, value]) => {
-      return [key.replace(targetDir, '.'), value]
-    }),
+    Object.entries(output.files).map(([key, value]) => [
+      toCleanPath(key, targetDir),
+      value,
+    ]),
   )
 
   return output

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/file-helpers.ts

@@ -36,6 +36,16 @@ export function getBinaryFile(content: string): string | null {
   return null
 }
 
+/**
+ * Convert an absolute path to a clean relative path by removing a base directory.
+ * Returns a path without leading ./ or / prefix.
+ */
+export function toCleanPath(absolutePath: string, baseDir: string): string {
+  let cleanPath = absolutePath.replace(baseDir, '')
+  if (cleanPath.startsWith('/')) cleanPath = cleanPath.slice(1)
+  return cleanPath
+}
+
 export function relativePath(
   from: string,
   to: string,
@@ -122,7 +132,7 @@ async function recursivelyGatherFilesHelper(
       )
     } else {
       const filePath = resolve(path, file.name)
-      files[filePath.replace(basePath, '.')] = await readFileHelper(filePath)
+      files[toCleanPath(filePath, basePath)] = await readFileHelper(filePath)
     }
   }
 }
@@ -159,7 +169,7 @@ async function recursivelyGatherFilesFromEnvironmentHelper(
       )
     } else {
       const filePath = resolve(path, file)
-      files[filePath.replace(basePath, '.')] =
+      files[toCleanPath(filePath, basePath)] =
         await environment.readFile(filePath)
     }
   }
@@ -232,7 +242,7 @@ export function cleanUpFiles(
 ) {
   return Object.keys(files).reduce<Record<string, string>>((acc, file) => {
     if (basename(file) !== '.cta.json') {
-      acc[targetDir ? file.replace(targetDir, '.') : file] = files[file]
+      acc[targetDir ? toCleanPath(file, targetDir) : file] = files[file]
     }
     return acc
   }, {})
@@ -241,7 +251,7 @@ export function cleanUpFiles(
 export function cleanUpFileArray(files: Array<string>, targetDir?: string) {
   return files.reduce<Array<string>>((acc, file) => {
     if (basename(file) !== '.cta.json') {
-      acc.push(targetDir ? file.replace(targetDir, '.') : file)
+      acc.push(targetDir ? toCleanPath(file, targetDir) : file)
     }
     return acc
   }, [])

package/src/frameworks.ts

@@ -5,6 +5,7 @@ import {
   findFilesRecursively,
   isDirectory,
   readFileHelper,
+  toCleanPath,
 } from './file-helpers.js'
 
 import type { AddOn, Framework, FrameworkDefinition } from './types.js'
@@ -20,7 +21,7 @@ export function scanProjectDirectory(
 
   const files = Object.keys(absolutePaths).reduce(
     (acc, path) => {
-      acc[path.replace(baseDirectory, '.')] = absolutePaths[path]
+      acc[toCleanPath(path, baseDirectory)] = absolutePaths[path]
       return acc
     },
     {} as Record<string, string>,
@@ -59,13 +60,16 @@ export function scanAddOnDirectories(addOnsDirectories: Array<string>) {
 
       let packageAdditions: Record<string, any> = {}
       let packageTemplate: string | undefined = undefined
-      
+
       if (existsSync(resolve(addOnsBase, dir, 'package.json'))) {
         packageAdditions = JSON.parse(
           readFileSync(resolve(addOnsBase, dir, 'package.json'), 'utf-8'),
         )
       } else if (existsSync(resolve(addOnsBase, dir, 'package.json.ejs'))) {
-        packageTemplate = readFileSync(resolve(addOnsBase, dir, 'package.json.ejs'), 'utf-8')
+        packageTemplate = readFileSync(
+          resolve(addOnsBase, dir, 'package.json.ejs'),
+          'utf-8',
+        )
       }
 
       let readme: string | undefined
@@ -88,7 +92,7 @@ export function scanAddOnDirectories(addOnsDirectories: Array<string>) {
       }
       const files: Record<string, string> = {}
       for (const file of Object.keys(absoluteFiles)) {
-        files[file.replace(assetsDir, '.')] = readFileHelper(file)
+        files[toCleanPath(file, assetsDir)] = readFileHelper(file)
       }
 
       const getFiles = () => {

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'
@@ -41,6 +46,7 @@ export {
   getBinaryFile,
   recursivelyGatherFiles,
   relativePath,
+  toCleanPath,
 } from './file-helpers.js'
 
 export { formatCommand, handleSpecialURL } from './utils.js'
@@ -85,6 +91,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
+}

package/tests/add-to-app.test.ts

@@ -34,7 +34,7 @@ const fakeCTAJSON: PersistedOptions = {
 
 beforeEach(() => {
   const fakeFiles = {
-    './package.json': JSON.stringify({
+    'package.json': JSON.stringify({
       name: 'test',
       version: '1.0.0',
       dependencies: {},
@@ -71,7 +71,7 @@ beforeEach(() => {
           },
         },
         dependsOn: [],
-        getFiles: () => Promise.resolve(['./jack.txt']),
+        getFiles: () => Promise.resolve(['jack.txt']),
         getFileContents: () => Promise.resolve('foo'),
         getDeletedFiles: () => Promise.resolve([]),
       },
@@ -152,8 +152,8 @@ describe('writeFiles', () => {
       '/foo',
       {
         files: {
-          './bar.txt': 'baz',
-          './blarg.txt': 'blarg',
+          'bar.txt': 'baz',
+          'blarg.txt': 'blarg',
         },
         deletedFiles: [],
       },
@@ -177,8 +177,8 @@ describe('writeFiles', () => {
       '/foo',
       {
         files: {
-          './bar.txt': 'baz',
-          './blarg.txt': 'blarg',
+          'bar.txt': 'baz',
+          'blarg.txt': 'blarg',
         },
         deletedFiles: [],
       },
@@ -186,9 +186,9 @@ describe('writeFiles', () => {
     )
     environment.finishRun()
     expect(output.files).toEqual({
-      './blooop.txt': 'blooop',
-      './bar.txt': 'baz',
-      './blarg.txt': 'blarg',
+      'blooop.txt': 'blooop',
+      'bar.txt': 'baz',
+      'blarg.txt': 'blarg',
     })
   })
 
@@ -203,9 +203,9 @@ describe('writeFiles', () => {
       '/foo',
       {
         files: {
-          './unchanged.jpg': 'base64::foobaz',
-          './changing.jpg': 'base64::aGVsbG8=',
-          './new.jpg': 'base64::aGVsbG8=',
+          'unchanged.jpg': 'base64::foobaz',
+          'changing.jpg': 'base64::aGVsbG8=',
+          'new.jpg': 'base64::aGVsbG8=',
         },
         deletedFiles: [],
       },
@@ -214,9 +214,9 @@ describe('writeFiles', () => {
     environment.finishRun()
     // It's ok for unchanged.jpg not to be written, because it matches the existing file
     expect(output.files).toEqual({
-      './unchanged.jpg': 'base64::foobaz',
-      './changing.jpg': 'base64::aGVsbG8=',
-      './new.jpg': 'base64::aGVsbG8=',
+      'unchanged.jpg': 'base64::foobaz',
+      'changing.jpg': 'base64::aGVsbG8=',
+      'new.jpg': 'base64::aGVsbG8=',
     })
   })
 
@@ -245,7 +245,7 @@ describe('writeFiles', () => {
       '/foo',
       {
         files: {
-          './package.json': JSON.stringify(
+          'package.json': JSON.stringify(
             {
               scripts: {
                 test: 'echo "test"',
@@ -264,7 +264,7 @@ describe('writeFiles', () => {
     )
     environment.finishRun()
     expect(output.files).toEqual({
-      './package.json': JSON.stringify(
+      'package.json': JSON.stringify(
         {
           name: 'test',
           version: '1.0.0',
@@ -291,11 +291,11 @@ describe('writeFiles', () => {
     await writeFiles(
       environment,
       '/foo',
-      { files: {}, deletedFiles: ['./bloop.txt'] },
+      { files: {}, deletedFiles: ['bloop.txt'] },
       true,
     )
     environment.finishRun()
-    expect(output.deletedFiles).toEqual(['./bloop.txt'])
+    expect(output.deletedFiles).toEqual(['bloop.txt'])
   })
 })
 
@@ -338,8 +338,8 @@ describe('addToApp', () => {
     })
     environment.finishRun()
     expect(output.files).toEqual({
-      './jack.txt': 'foo',
-      './package.json': JSON.stringify(
+      'jack.txt': 'foo',
+      'package.json': JSON.stringify(
         {
           name: 'test',
           version: '1.0.0',

package/tests/create-app.test.ts

@@ -35,7 +35,7 @@ const simpleOptions = {
         },
       },
     },
-    getFiles: () => ['./src/test.txt'],
+    getFiles: () => ['src/test.txt'],
     getFileContents: () => 'Hello',
     getDeletedFiles: () => [],
   },
@@ -78,7 +78,7 @@ describe('createApp', () => {
           command: 'echo',
           args: ['Hello'],
         },
-        getFiles: () => ['./src/test2.txt'],
+        getFiles: () => ['src/test2.txt'],
         getFileContents: () => 'Hello-2',
         getDeletedFiles: () => [],
       } as unknown as AddOn,
@@ -106,7 +106,7 @@ describe('createApp', () => {
             dependencies: {},
             devDependencies: {},
           },
-          getFiles: () => ['./src/test2.txt', './public/foo.jpg'],
+          getFiles: () => ['src/test2.txt', 'public/foo.jpg'],
           getFileContents: () => 'base64::aGVsbG8=',
           getDeletedFiles: () => [],
         } as unknown as AddOn,