@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/efcore/agents/list.md

@@ -0,0 +1,35 @@
+# Agent — List migrations
+
+Read `_shared.md` first.
+
+## Goal
+
+Return a snapshot of the EF Core migration state in the current worktree.
+Never mutate anything.
+
+## Steps
+
+1. Resolve the worktree path (usually `$CWD` or the path passed in).
+2. Invoke the CLI:
+
+   ```bash
+   npx tsx skills/efcore/cli/list/index.ts --spec '{"cwd":"<WORKTREE>"}'
+   ```
+
+3. Parse the JSON output. Display the result grouped by context, then by
+   assembly. For each migration, show whether it is applied.
+
+## What to highlight
+
+- The detected `kind` (`generated`, `studio`, or `unknown`) helps the user
+  understand which DbContext pattern they are working against.
+- `warnings[]` contains actionable items (missing `dotnet-ef`, no csproj,
+  …) — surface these clearly.
+- If `assemblies[i].error` is set, the list for that assembly failed.
+  Report the error and move on — do not fail the whole report.
+
+## What NOT to do
+
+- Do not create, delete, or modify files.
+- Do not run `dotnet ef database update`.
+- Do not call `create`, `squash`, or `rebase-snapshot` from this agent.

package/templates/skills/efcore/agents/rebase-snapshot.md

@@ -0,0 +1,50 @@
+# Agent — Rebase-snapshot (fix snapshot conflicts)
+
+Read `_shared.md` first.
+
+## Goal
+
+Resync `ModelSnapshot.cs` after a `git rebase` pulled in changes that
+conflict with the local branch's snapshot. The CLI re-uses the squash
+mechanics to re-anchor the snapshot on the base ref, delete branch-only
+migrations, then regenerate a single consolidated migration on top.
+
+## When to use this
+
+- `git rebase develop` emitted merge conflicts on `ModelSnapshot.cs`.
+- Snapshot shows surprising schema after a pull — the model no longer
+  matches any migration.
+- Squash would work but the branch has already been rebased.
+
+## Steps
+
+1. Abort or resolve the rebase *except* for the snapshot file. Leave the
+   snapshot in its conflicted state — the CLI will reset it.
+
+2. Dry-run:
+
+   ```bash
+   npx tsx skills/efcore/cli/rebase-snapshot/index.ts --spec '{
+     "cwd": "<WORKTREE>",
+     "contextName": "CoreDbContext",
+     "description": "FeatureOnRebased",
+     "dryRun": true
+   }'
+   ```
+
+3. Review: what gets deleted, which snapshot gets reset, new migration
+   name. Confirm with the user.
+
+4. Run for real. The CLI performs exactly the squash workflow but intent
+   is post-rebase recovery.
+
+5. `dotnet build` to verify. If it fails, check:
+   - The DbContext file — did the rebase leave stale entities?
+   - The Migrations folder — any stragglers still around?
+
+## What NOT to do
+
+- Do not run this without first finishing (or aborting) the rebase.
+- Do not run it while there are uncommitted non-snapshot changes in the
+  migrations folder — they will be caught in the backup but it muddies
+  recovery.

package/templates/skills/efcore/agents/recreate-db.md

@@ -0,0 +1,78 @@
+# Agent — Recreate the database
+
+Read `_shared.md` first. There is **no** CLI colocated with this agent —
+the two `dotnet ef` invocations are straightforward enough that the agent
+runs them directly with the correct parameters.
+
+## Goal
+
+Drop the target database and reapply every migration from scratch. Used in
+local development when the schema has drifted too far from the migrations
+or when the user wants a clean slate. **Destructive** — the caller (Studio
+MigrationsTab) always asks for explicit confirmation before invoking this
+agent.
+
+## Refuses to run when
+
+- The connection string points to anything labelled `prod` / `production`
+  / `staging`. When in doubt, bail and ask the user.
+- Multiple DbContexts resolve to the same physical database (avoid
+  dropping Core while Extensions still depends on it).
+
+## Steps
+
+1. Resolve the target DbContext + migration assembly from the spec
+   (passed by the MigrationsTab or by the user):
+   - `contextName` — e.g. `CoreDbContext`, `ExtensionsDbContext`, `StudioDbContext`.
+   - `assembly`    — the migrations project. For the Studio, pick the one
+     matching the active provider from `~/.smartstack/config.json`
+     (Sqlite / Postgres / SqlServer).
+   - `startupProject` — auto-detected (Host / Api / Web) unless overridden.
+
+2. Dump the idempotent SQL script so the user has a record of what will
+   run after the drop:
+
+   ```bash
+   dotnet ef migrations script --idempotent \
+     --project <csproj> \
+     --context <contextName> \
+     --startup-project <startup> \
+     -o recreate-<contextName>.sql
+   ```
+
+3. Drop the database:
+
+   ```bash
+   dotnet ef database drop --force --no-color \
+     --project <csproj> \
+     --context <contextName> \
+     --startup-project <startup>
+   ```
+
+   `--force` skips the interactive confirmation since the caller already
+   asked the user.
+
+4. Apply every migration:
+
+   ```bash
+   dotnet ef database update --no-color \
+     --project <csproj> \
+     --context <contextName> \
+     --startup-project <startup>
+   ```
+
+5. Dual-context apps (Core + Extensions): always `Core` first, then
+   `Extensions`. Extensions' FKs reference Core tables.
+
+6. Report: `dropped ✓`, `applied N migrations`, and any seed data the
+   user might want to re-run manually.
+
+## What NOT to do
+
+- Never call this against a connection string tagged `prod` or
+  `production`. The caller is responsible for checking the environment but
+  the agent MUST verify too before running the drop.
+- Never run this on a schema shared with another app without also
+  dropping that app's contexts — otherwise you leave orphan FKs.
+- Never skip the idempotent script. It's the user's only paper trail if
+  they lose data in step 3.

package/templates/skills/efcore/agents/squash.md

@@ -0,0 +1,78 @@
+# Agent — Squash branch migrations
+
+Read `_shared.md` first.
+
+## Goal
+
+Collapse all branch-only migrations into a single consolidated migration
+right before merging the feature to develop. The CLI handles the
+mechanical parts (backup / delete / reset / regenerate) but you still own
+the decision to run it.
+
+## Preconditions
+
+- Working tree is clean (no unstaged changes other than the migrations
+  being squashed). Ask the user to stash or commit first.
+- Current branch is NOT `main` / `master` — the CLI refuses otherwise.
+- `base` ref is fetchable (usually `origin/develop`). If the user is
+  offline or has no `origin/develop`, pass `baseBranch` explicitly.
+
+## Steps
+
+1. Run `status` first to see how many branch-only migrations exist:
+
+   ```bash
+   npx tsx skills/efcore/cli/status/index.ts --spec '{"cwd":"<WORKTREE>"}'
+   ```
+
+   If fewer than 2, there is nothing to squash — stop.
+
+2. Dry-run the squash:
+
+   ```bash
+   npx tsx skills/efcore/cli/squash/index.ts --spec '{
+     "cwd": "<WORKTREE>",
+     "contextName": "CoreDbContext",
+     "description": "FeatureXYZConsolidated",
+     "dryRun": true
+   }'
+   ```
+
+3. Review the plan: which files will be deleted, which snapshot will be
+   reset, the consolidated migration name. Confirm with the user.
+
+4. Run the real squash (same spec, remove `dryRun`). The CLI:
+   - Writes a backup under `.efcore-squash-backup/<timestamp>/<Assembly>/`.
+   - Deletes branch-only migration files and their `.Designer.cs`.
+   - Resets the snapshot with `git checkout <baseRef> -- <snapshot>`.
+   - Runs `dotnet ef migrations add <consolidated_name>` to regenerate
+     one migration that reflects every cumulative change.
+
+5. Run `dotnet build` to verify the solution compiles. If it fails,
+   restore from the backup and investigate.
+
+6. Commit the single new migration. The commit message should reference
+   the feature and note that the previous N commits' migrations have
+   been consolidated.
+
+## Recovery
+
+If something went wrong:
+
+```bash
+cp -r .efcore-squash-backup/<timestamp>/<Assembly>/* .
+git checkout HEAD -- path/to/ModelSnapshot.cs
+```
+
+then remove the partially-generated consolidated migration:
+
+```bash
+dotnet ef migrations remove --context <context> --project <csproj> --startup-project <startup>
+```
+
+## What NOT to do
+
+- Never squash on `main` or `master`.
+- Never skip the backup by editing the CLI to disable it.
+- Never delete the `.efcore-squash-backup/` directory before validating
+  the new migration in a real database (at least in dev).

package/templates/skills/efcore/agents/status.md

@@ -0,0 +1,35 @@
+# Agent — Migration status
+
+Read `_shared.md` first.
+
+## Goal
+
+Summarize per-assembly migration health: total, applied, pending, branch-only
+count, and whether the snapshot is dirty. Never mutate.
+
+## Steps
+
+1. Invoke the CLI:
+
+   ```bash
+   npx tsx skills/efcore/cli/status/index.ts --spec '{"cwd":"<WORKTREE>"}'
+   ```
+
+2. For each assembly reported:
+   - Show counts (`total` / `applied` / `pending`).
+   - List `branchOnly` migrations (files present on the current branch
+     that are absent on the base ref).
+   - Flag `snapshotDirty: true` — the user has unstaged snapshot changes.
+
+## Decisions
+
+- If any assembly has `pending > 0`, recommend `agents/db-update.md`.
+- If `branchOnly.length >= 2`, recommend `agents/squash.md` before merging
+  to develop.
+- If `snapshotDirty` and no migration is in flight, warn: the snapshot
+  shouldn't change without a matching migration file.
+
+## What NOT to do
+
+- Never fix snapshot drift silently — always route to `rebase-snapshot` or
+  `squash` agents for that.

package/templates/skills/efcore/cli/create/execute.ts

@@ -0,0 +1,164 @@
+import path from 'node:path';
+import { findFiles } from '../../../lib/fs.js';
+import { detectDbContexts, findStartupProject, hasDotnetProject } from '../lib/detect-dbcontexts.js';
+import { runDotnet, dotnetAvailable, dotnetEfAvailable } from '../lib/ef-runner.js';
+import { buildMigrationName } from '../lib/migration-name.js';
+import type { CreateSpec, CreateResult, CreateAssemblyResult } from './types.js';
+
+function capitalize(s: string): string {
+  if (!s) return s;
+  if (s.toLowerCase() === 'sqlserver') return 'SqlServer';
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+async function countExistingMigrations(migrationsDir: string): Promise<number> {
+  const files = await findFiles('*.cs', { cwd: migrationsDir });
+  return files.filter(
+    (f) =>
+      !f.endsWith('ModelSnapshot.cs') &&
+      !f.endsWith('.Designer.cs') &&
+      path.dirname(f) === migrationsDir,
+  ).length;
+}
+
+export async function execute(spec: CreateSpec): Promise<CreateResult> {
+  const warnings: string[] = [];
+
+  if (!(await hasDotnetProject(spec.cwd))) {
+    return {
+      success: false,
+      cwd: spec.cwd,
+      contextName: spec.contextName,
+      assemblies: [],
+      warnings,
+      error: 'No .csproj in worktree — cannot create a migration.',
+    };
+  }
+
+  if (!spec.dryRun) {
+    if (!(await dotnetAvailable())) {
+      return {
+        success: false,
+        cwd: spec.cwd,
+        contextName: spec.contextName,
+        assemblies: [],
+        warnings,
+        error: 'dotnet CLI is not available on PATH',
+      };
+    }
+    if (!(await dotnetEfAvailable())) {
+      return {
+        success: false,
+        cwd: spec.cwd,
+        contextName: spec.contextName,
+        assemblies: [],
+        warnings,
+        error: 'dotnet-ef is not installed — run: dotnet tool install --global dotnet-ef',
+      };
+    }
+  }
+
+  const detection = await detectDbContexts(spec.cwd);
+  const ctx = detection.contexts.find((c) => c.name === spec.contextName);
+  if (!ctx) {
+    return {
+      success: false,
+      cwd: spec.cwd,
+      contextName: spec.contextName,
+      assemblies: [],
+      warnings,
+      error: `Context "${spec.contextName}" not found in worktree. Detected: ${detection.contexts.map((c) => c.name).join(', ') || 'none'}`,
+    };
+  }
+
+  const targetAssemblies = spec.assembly
+    ? ctx.assemblies.filter((a) => a.assemblyName === spec.assembly)
+    : spec.allProviders
+      ? ctx.assemblies
+      : [ctx.assemblies[0]].filter(Boolean);
+
+  if (targetAssemblies.length === 0) {
+    return {
+      success: false,
+      cwd: spec.cwd,
+      contextName: spec.contextName,
+      assemblies: [],
+      warnings,
+      error: spec.assembly
+        ? `Assembly "${spec.assembly}" not found for context ${spec.contextName}`
+        : `No migration assembly detected for context ${spec.contextName}`,
+    };
+  }
+
+  const startupProject = spec.startupProject ?? (await findStartupProject(spec.cwd)) ?? undefined;
+  if (!startupProject && !spec.dryRun) {
+    warnings.push('No startup project detected — dotnet ef may fail. Pass --startupProject if necessary.');
+  }
+
+  const results: CreateAssemblyResult[] = [];
+
+  for (const asm of targetAssemblies) {
+    const sequence = (await countExistingMigrations(asm.migrationsDir)) + 1;
+    const migrationName = buildMigrationName({
+      contextName: spec.contextName,
+      version: asm.version,
+      sequence,
+      description: spec.description,
+    });
+
+    if (spec.dryRun) {
+      results.push({
+        assemblyName: asm.assemblyName,
+        migrationName,
+        csprojPath: asm.csprojPath,
+        output: `[dry-run] dotnet ef migrations add ${migrationName} --project ${asm.csprojPath} --context ${spec.contextName}${startupProject ? ` --startup-project ${startupProject}` : ''}`,
+        success: true,
+        filesCreated: [],
+      });
+      continue;
+    }
+
+    const extraEnv = asm.provider ? { STUDIO_DESIGN_PROVIDER: capitalize(asm.provider) } : undefined;
+
+    const args = [
+      'ef', 'migrations', 'add', migrationName,
+      '--project', asm.csprojPath,
+      '--context', spec.contextName,
+      '--no-color',
+    ];
+    if (startupProject) {
+      args.push('--startup-project', startupProject);
+    }
+
+    const r = await runDotnet(args, spec.cwd, { timeoutMs: 5 * 60_000, extraEnv });
+    const success = r.exitCode === 0;
+
+    const filesCreated = success
+      ? [
+          path.join(asm.migrationsDir, `${migrationName}.cs`),
+          path.join(asm.migrationsDir, `${migrationName}.Designer.cs`),
+          asm.snapshotPath,
+        ]
+      : [];
+
+    results.push({
+      assemblyName: asm.assemblyName,
+      migrationName,
+      csprojPath: asm.csprojPath,
+      output: `${r.stdout}${r.stderr ? `\n${r.stderr}` : ''}`,
+      success,
+      error: success ? undefined : r.stderr || r.stdout || 'dotnet ef migrations add failed',
+      filesCreated,
+    });
+  }
+
+  const allOk = results.every((r) => r.success);
+  return {
+    success: allOk,
+    cwd: detection.cwd,
+    contextName: spec.contextName,
+    assemblies: results,
+    warnings,
+    error: allOk ? undefined : 'One or more assemblies failed to add migration — see per-assembly error',
+  };
+}

package/templates/skills/efcore/cli/create/index.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * cli:efcore-create — Scaffold a new EF Core migration with automatic naming.
+ *
+ * Naming convention (no MCP): {contextPrefix}_v{version_underscore}_{seq3}_{PascalCaseDescription}
+ *
+ * Usage:
+ *   npx tsx skills/efcore/cli/create/index.ts --spec '{
+ *     "cwd": "D:/path/to/worktree",
+ *     "contextName": "CoreDbContext",
+ *     "description": "AddEmployeeAvatar"
+ *   }'
+ */
+import { parseArgs } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import { validate } from './validate.js';
+import { execute } from './execute.js';
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    options: {
+      spec: { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+
+  if (values.help || !values.spec) {
+    console.log(`Usage: npx tsx skills/efcore/cli/create/index.ts --spec '{"cwd":"...","contextName":"CoreDbContext","description":"AddFoo"}'`);
+    process.exit(values.help ? 0 : 1);
+  }
+
+  let raw: unknown;
+  try {
+    raw = existsSync(values.spec!) ? JSON.parse(readFileSync(values.spec!, 'utf-8')) : JSON.parse(values.spec!);
+  } catch (err) {
+    console.log(JSON.stringify({ success: false, error: `Invalid JSON: ${(err as Error).message}` }, null, 2));
+    process.exit(1);
+  }
+
+  const validation = validate(raw);
+  if (!validation.valid || !validation.data) {
+    console.log(JSON.stringify({ success: false, errors: validation.blockers, warnings: validation.warnings }, null, 2));
+    process.exit(1);
+  }
+
+  const result = await execute(validation.data);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.success ? 0 : 1);
+}
+
+void main();

package/templates/skills/efcore/cli/create/types.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+export const CreateSpecSchema = z.object({
+  cwd: z.string().min(1),
+  contextName: z.string().min(1),
+  description: z.string().min(1),
+  /** Optional: target a single migration assembly (required for multi-provider contexts unless allProviders=true). */
+  assembly: z.string().optional(),
+  /** For multi-provider contexts (Studio), create the migration in EVERY assembly. Default: true. */
+  allProviders: z.boolean().optional().default(true),
+  /** Optional override of the startup project used by `dotnet ef`. */
+  startupProject: z.string().optional(),
+  /** Dry-run: compute name + paths, do NOT spawn dotnet. */
+  dryRun: z.boolean().optional().default(false),
+});
+export type CreateSpec = z.infer<typeof CreateSpecSchema>;
+
+export interface CreateAssemblyResult {
+  assemblyName: string;
+  migrationName: string;
+  csprojPath: string;
+  output: string;
+  success: boolean;
+  error?: string;
+  filesCreated: string[];
+}
+
+export interface CreateResult {
+  success: boolean;
+  cwd: string;
+  contextName: string;
+  assemblies: CreateAssemblyResult[];
+  warnings: string[];
+  error?: string;
+}

package/templates/skills/efcore/cli/create/validate.ts

@@ -0,0 +1,29 @@
+import { CreateSpecSchema, type CreateSpec } from './types.js';
+import { toPascalCase } from '../lib/migration-name.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  data?: CreateSpec;
+  blockers: string[];
+  warnings: string[];
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const parsed = CreateSpecSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      valid: false,
+      blockers: parsed.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`),
+      warnings: [],
+    };
+  }
+  const data = parsed.data;
+  const blockers: string[] = [];
+  const warnings: string[] = [];
+
+  const desc = toPascalCase(data.description);
+  if (!desc) blockers.push('[description] must contain at least one alphanumeric character');
+  if (desc && desc.length > 60) warnings.push('description is long (>60 chars after PascalCase) — keep it concise');
+
+  return { valid: blockers.length === 0, data, blockers, warnings };
+}