deepspace 0.5.5 → 0.5.6

package/features/admin-page/feature.json

@@ -24,6 +24,8 @@
     "protected": true
   },
   "requires": [],
-  "instructions": [],
+  "instructions": [
+    "This layers an admin-only /admin panel on top of the /settings page that every scaffold already ships (that shared src/schemas/admin-schema.ts is why it reports \"Exists (skipped)\" here). Add a nav entry for /admin; keep /settings for per-user settings."
+  ],
   "patterns": []
 }

package/features/file-attachments/feature.json

@@ -27,11 +27,13 @@
     "@codemirror/lang-javascript": "^6.2.2",
     "@codemirror/theme-one-dark": "^6.1.2",
     "papaparse": "^5.4.1",
-    "@types/papaparse": "^5.3.0",
     "docx-preview": "^0.3.5",
     "exceljs": "^4.4.0",
     "pdfjs-dist": "^4.7.76"
   },
+  "devDependencies": {
+    "@types/papaparse": "^5.3.0"
+  },
   "instructions": [],
   "patterns": [
     "useMimeTypeDetection() → { detectMimeType, getFileCategory, getExtension, canPreview }",

package/features/messaging/feature.json

@@ -105,7 +105,7 @@
   },
   "requires": [],
   "instructions": [
-    "Optionally add a second route for /chat-multi -> ChatMultiPage"
+    "Optionally add a nav entry for /chat-multi (the multi-channel view). Its route is created automatically from the bundled page file — only the nav link is manual."
   ],
   "patterns": []
 }

package/features/search-bar/feature.json

@@ -12,11 +12,12 @@
   ],
   "requires": [],
   "instructions": [
-    "Run npx deepspace add search-bar before building any search UI that filters records or displays results; it only installs src/components/search/SearchOverlay.tsx and does not add app routes.",
-    "Prefer InlineSearch + useSearchIndex for simple page, feed, table, list, picker, or RecordRoom filtering instead of composing SearchInput manually.",
-    "Use the raw SearchInput primitive only when you need a bare input with no result list, ranking, keyboard navigation, empty state, or selection handling.",
-    "Use InlineSearch when search belongs to a specific page section and results should appear beneath that input.",
-    "Use SearchOverlay when search is temporary, global, command-like, includes recent searches, submits partial text to a search-results page, or should interrupt the current workflow.",
+    "Installs src/components/search/SearchOverlay.tsx (exports InlineSearch, SearchOverlay, and useSearchIndex). It adds no route — import what you need into your own page.",
+    "Use InlineSearch + useSearchIndex for in-page filtering (lists, feeds, tables, pickers, RecordRoom records); use SearchOverlay for global/command-style search.",
+    "Use the raw SearchInput primitive only for a bare input with no result list, ranking, keyboard navigation, or selection handling."
+  ],
+  "agentNotes": [
+    "Use InlineSearch when search belongs to a specific page section and results should appear beneath that input; use SearchOverlay when search is temporary, global, command-like, includes recent searches, submits partial text to a search-results page, or should interrupt the current workflow.",
     "Pass onSearchSubmit when pressing Enter should navigate to or render a full search-results page for the typed query; result clicks still call onSelect.",
     "Ask the user which placement they prefer only when both overlay and inline search are plausible and the page context does not make the placement obvious.",
     "Use SearchOverlay's recentStorageKey, maxRecentItems, and showRecentSearches props when recent selections or submitted text queries should appear before the user types; keep recent searches off inline controls unless the surrounding UI has room for them.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepspace",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "engines": {
     "node": ">=22.15.0"
   },

package/scripts/add-feature.cjs

@@ -12,6 +12,8 @@
 const fs = require('fs')
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- CommonJS (.cjs) module: require is required
 const path = require('path')
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- CommonJS (.cjs) module: require is required
+const { spawnSync } = require('child_process')
 
 // ---------------------------------------------------------------------------
 // Environment-aware features path resolution
@@ -90,6 +92,107 @@ function groupByCategory(features) {
   return groups
 }
 
+// First feature id in display order — used for a never-stale help example.
+function firstFeatureId(groups) {
+  for (const category of CATEGORY_ORDER) {
+    const list = groups.get(category)
+    if (list && list.length > 0) return list[0].id
+  }
+  return null
+}
+
+// Small edit distance for "did you mean" suggestions on a typo'd feature id.
+function levenshtein(a, b) {
+  const m = a.length
+  const n = b.length
+  const row = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    let prev = row[0]
+    row[0] = i
+    for (let j = 1; j <= n; j++) {
+      const tmp = row[j]
+      row[j] = Math.min(
+        row[j] + 1,
+        row[j - 1] + 1,
+        prev + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+      prev = tmp
+    }
+  }
+  return row[n]
+}
+
+// Closest visible feature id to a typo, or null when nothing is close enough.
+function suggestFeature(featureId) {
+  let best = null
+  let bestD = Infinity
+  for (const f of listFeatures()) {
+    const d = levenshtein(featureId, f.id)
+    if (d < bestD) {
+      bestD = d
+      best = f.id
+    }
+  }
+  const threshold = Math.max(2, Math.floor(featureId.length / 3))
+  return best && bestD <= threshold ? best : null
+}
+
+// Print a friendly unknown-feature error (with a suggestion) and exit.
+function unknownFeature(featureId) {
+  console.error(`\nError: Unknown feature: ${featureId}`)
+  const guess = suggestFeature(featureId)
+  if (guess) console.error(`Did you mean "${guess}"?`)
+  console.error('Run `deepspace add --list` to see available features')
+  process.exit(1)
+}
+
+// Detect the target app's package manager from its lockfile (defaults to npm).
+function detectPackageManager(targetDir) {
+  const has = (f) => fs.existsSync(path.join(targetDir, f))
+  if (has('pnpm-lock.yaml')) return 'pnpm'
+  if (has('yarn.lock')) return 'yarn'
+  if (has('bun.lockb') || has('bun.lock')) return 'bun'
+  return 'npm'
+}
+
+// The nav features are mutually exclusive (competing navigation). Derive which
+// are installed from the catalog itself — each nav feature's first installed
+// file is its signature — so this never drifts from what a feature ships.
+function installedNavFeatures(targetDir) {
+  return listFeatures()
+    .filter((f) => f.category === 'nav' && Array.isArray(f.files) && f.files.length > 0)
+    .filter((f) =>
+      fs.existsSync(path.join(targetDir, resolveDestPath(f.files[0].dest, f.route))),
+    )
+    .map((f) => f.id)
+}
+
+function warnNavConflicts(config, targetDir) {
+  if (config.category !== 'nav') return
+  const present = installedNavFeatures(targetDir)
+  if (present.length > 1) {
+    console.log(`\n⚠ Multiple navigation features present (${present.join(', ')}).`)
+    console.log(
+      '  sidebar, topbar, and tree are mutually exclusive — keep one and remove the',
+    )
+    console.log('  others to avoid competing navigation in your layout.')
+  }
+}
+
+// Always-printed footer so every install ends with a clear "what now".
+function printNextSteps(config, deps) {
+  console.log('\nNext steps:')
+  let n = 1
+  if (deps.added.length > 0 && !deps.installRan) {
+    console.log(`  ${n++}. Install new dependencies: ${deps.pm} install`)
+    console.log('     (or re-run this command with --install to do it for you)')
+  }
+  console.log(`  ${n++}. Start the dev server: deepspace dev`)
+  if (config.route && config.route.path) {
+    console.log(`  ${n++}. Open ${config.route.path} once the dev server is up`)
+  }
+}
+
 function copyFile(src, dest) {
   const destDir = path.dirname(dest)
   if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true })
@@ -437,7 +540,9 @@ function printRouteInstructions(route, config) {
  * but easy to get wrong; deferring to the user keeps the contract
  * narrow and respects whatever lockfile setup they have.
  */
-function integrateDependencies(config, targetDir) {
+function integrateDependencies(config, targetDir, options = {}) {
+  const result = { added: [], installRan: false, pm: detectPackageManager(targetDir) }
+
   const sections = [
     { key: 'dependencies', label: 'dependencies' },
     { key: 'devDependencies', label: 'devDependencies' },
@@ -445,12 +550,12 @@ function integrateDependencies(config, targetDir) {
 
   // Skip the work if nothing is declared.
   const hasAny = sections.some((s) => config[s.key] && Object.keys(config[s.key]).length > 0)
-  if (!hasAny) return
+  if (!hasAny) return result
 
   const pkgPath = path.join(targetDir, 'package.json')
   if (!fs.existsSync(pkgPath)) {
     console.log('   Could not patch package.json (file not found)')
-    return
+    return result
   }
 
   let pkg
@@ -458,7 +563,7 @@ function integrateDependencies(config, targetDir) {
     pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
   } catch (err) {
     console.log(`   Could not patch package.json (parse error: ${err.message})`)
-    return
+    return result
   }
 
   const added = []
@@ -469,8 +574,13 @@ function integrateDependencies(config, targetDir) {
     if (!declared) continue
     pkg[key] = pkg[key] || {}
     for (const [name, version] of Object.entries(declared)) {
-      if (pkg[key][name]) {
-        skipped.push(name)
+      // Skip if already declared in this OR the sibling section — never let a
+      // package land in both dependencies and devDependencies (e.g. when a
+      // feature moves a dep between sections across versions). Don't report a
+      // name we added moments ago (from the sibling section of this same
+      // config) as "already present" — that would list it as both added+skipped.
+      if (pkg.dependencies?.[name] || pkg.devDependencies?.[name]) {
+        if (!added.includes(name)) skipped.push(name)
         continue
       }
       pkg[key][name] = version
@@ -480,7 +590,7 @@ function integrateDependencies(config, targetDir) {
 
   if (added.length === 0) {
     console.log('   Dependencies already present')
-    return
+    return result
   }
 
   // Re-write with two-space indent (Node's de-facto default; matches
@@ -490,7 +600,31 @@ function integrateDependencies(config, targetDir) {
   if (skipped.length > 0) {
     console.log(`   Already present (kept your version): ${skipped.join(', ')}`)
   }
-  console.log('   ➜ Run `npm install` (or your package manager) before starting the dev server')
+  result.added = added
+
+  // Opt-in (--install): run the detected package manager for the user. By
+  // default we only patch package.json and let the "Next steps" footer tell
+  // them to install, so we never guess wrong about their PM/lockfile.
+  if (options.runInstall) {
+    console.log(`\n   Installing dependencies with ${result.pm}...`)
+    // shell:true on Windows, where npm/pnpm/yarn/bun are .cmd shims that
+    // spawnSync can't exec directly.
+    const res = spawnSync(result.pm, ['install'], {
+      cwd: targetDir,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    })
+    if (res.error) {
+      const why = res.error.code === 'ENOENT' ? `${result.pm} not found on PATH` : res.error.message
+      console.log(`   Could not launch ${result.pm} (${why}) — run "${result.pm} install" manually.`)
+    } else if (res.status === 0) {
+      result.installRan = true
+    } else {
+      console.log(`   ${result.pm} install did not complete — run "${result.pm} install" manually.`)
+    }
+  }
+
+  return result
 }
 
 // ---------------------------------------------------------------------------
@@ -513,21 +647,25 @@ function printPostInstallInstructions(config) {
 // ---------------------------------------------------------------------------
 
 function main() {
-  const args = process.argv.slice(2)
+  // Pull the `--install` flag out first so it can appear anywhere; the rest of
+  // main() treats args[0]/args[1] as feature + dir positionally.
+  const runInstall = process.argv.slice(2).includes('--install')
+  const args = process.argv.slice(2).filter((a) => a !== '--install')
 
   // --help
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log('\nFeature Installation Script\n')
-    console.log('Usage: node add-feature.js <feature-id> <app-dir>\n')
-    console.log('Commands:')
-    console.log('  <feature-id> <dir>  Install a feature into app dir')
-    console.log('  --list, -l          List all available features')
-    console.log('  --info <id>         Show detailed info about a feature')
-    console.log('  --help, -h          Show this help\n')
-
     const features = listFeatures()
     const groups = groupByCategory(features)
 
+    console.log('\nAdd a feature to your DeepSpace app\n')
+    console.log('Usage: deepspace add <feature> [dir]\n')
+    console.log('Commands:')
+    console.log('  <feature> [dir]     Install a feature (dir defaults to .)')
+    console.log('  --list, -l          List all available features')
+    console.log('  --info <feature>    Show detailed info about a feature')
+    console.log('  --install           Run your package manager after adding deps')
+    console.log('  --help, -h          Show this help')
+
     for (const category of CATEGORY_ORDER) {
       const categoryFeatures = groups.get(category)
       if (categoryFeatures && categoryFeatures.length > 0) {
@@ -538,9 +676,11 @@ function main() {
       }
     }
 
+    const example = firstFeatureId(groups) || '<feature>'
     console.log('\nExamples:')
-    console.log('  add feature items-crud .')
-    console.log('  node add-feature.js items-crud ../my-app')
+    console.log('  deepspace add --list')
+    console.log(`  deepspace add ${example}`)
+    console.log(`  deepspace add ${example} ./my-app`)
     process.exit(0)
   }
 
@@ -562,7 +702,7 @@ function main() {
       }
     }
 
-    console.log('Use: npx deepspace add <feature-id>')
+    console.log('Use: deepspace add <feature>')
     process.exit(0)
   }
 
@@ -574,11 +714,7 @@ function main() {
       process.exit(1)
     }
     const config = loadFeatureConfig(featureId)
-    if (!config) {
-      console.error(`\nError: Unknown feature: ${featureId}`)
-      console.error('Use --list to see available features')
-      process.exit(1)
-    }
+    if (!config) unknownFeature(featureId)
 
     console.log(`\n${config.name} (${config.id})`)
     if (config.category) {
@@ -617,16 +753,12 @@ function main() {
 
   if (!targetDir) {
     console.error('\nError: Please specify an app directory')
-    console.error('Usage: node add-feature.js <feature-id> <app-dir>')
+    console.error('Usage: deepspace add <feature> [dir]')
     process.exit(1)
   }
 
   const config = loadFeatureConfig(featureId)
-  if (!config) {
-    console.error(`\nError: Unknown feature: ${featureId}`)
-    console.error('Use --list to see available features')
-    process.exit(1)
-  }
+  if (!config) unknownFeature(featureId)
 
   if (!fs.existsSync(targetDir)) {
     console.error(`\nError: Target directory not found: ${targetDir}`)
@@ -650,11 +782,11 @@ function main() {
   // Add any new npm dependencies the feature declares to the target's
   // package.json. Without this, copied source files import packages
   // that don't exist in node_modules and the next `vite dev` blows up
-  // with a hard-to-diagnose "Failed to resolve import" error. We patch
-  // package.json (rather than running `npm install` ourselves) so the
-  // user keeps control over their package manager + lockfile, and we
-  // print a single clear instruction when changes were made.
-  integrateDependencies(config, targetDir)
+  // with a hard-to-diagnose "Failed to resolve import" error. By default we
+  // only patch package.json (the "Next steps" footer tells the user to
+  // install) so we never guess wrong about their package manager + lockfile;
+  // `--install` opts into running it for them.
+  const deps = integrateDependencies(config, targetDir, { runInstall })
 
   // Print any remaining manual wiring instructions
   printPostInstallInstructions(config)
@@ -664,6 +796,12 @@ function main() {
     config.patterns.forEach((p) => console.log(`- ${p}`))
     console.log('')
   }
+
+  // Warn when installing a nav feature alongside another (they're exclusive).
+  warnNavConflicts(config, targetDir)
+
+  // Always close with concrete next steps.
+  printNextSteps(config, deps)
 }
 
 main()

package/dist/testing.d.ts

@@ -1,115 +0,0 @@
-import * as _playwright_test from '@playwright/test';
-import { BrowserContext, Page, Browser } from '@playwright/test';
-export { expect } from '@playwright/test';
-
-interface MultiplayerUser {
-    context: BrowserContext;
-    page: Page;
-    email: string;
-    name: string;
-    /** Test account user ID, if known from the accounts registry. */
-    userId?: string;
-}
-/**
- * Fixture function signature. Pass either a count (`users(2)`) or an
- * array of account names (`users(['Alice', 'Bob'])`). Returns one entry
- * per requested user.
- */
-type UsersFixture = (selector: number | string[], options?: {
-    label?: string;
-}) => Promise<MultiplayerUser[]>;
-interface MultiplayerFixtures {
-    users: UsersFixture;
-}
-declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & MultiplayerFixtures, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
-
-/**
- * Account-credential plumbing for the testing module.
- *
- * Reads test accounts from `~/.deepspace/test-accounts.json` (the same
- * file `deepspace test-accounts create` writes). Each account has at
- * minimum `{email, password}`; `name` and `label` are optional.
- *
- * Used by the multi-user Playwright fixture in `./fixtures.ts` and is
- * also exported standalone in case suites want to do their own
- * orchestration.
- */
-interface TestAccount {
-    email: string;
-    password: string;
-    name?: string;
-    label?: string | null;
-    id?: string;
-    userId?: string;
-    createdAt?: number;
-}
-/**
- * Load all test accounts the developer has created. Returns an empty
- * array if the file doesn't exist yet.
- */
-declare function loadAllTestAccounts(): TestAccount[];
-/**
- * Pick `count` test accounts from the local registry, optionally
- * filtered by `label`. Order-stable: sorted by `createdAt` ascending so
- * the first test account you created is always the first one returned.
- *
- * Throws with a helpful message if not enough accounts exist.
- */
-declare function pickTestAccounts(count: number, options?: {
-    label?: string;
-}): TestAccount[];
-/**
- * Find a single account by name. Used by `users(['Alice', 'Bob'])`.
- * Throws if not found.
- */
-declare function findTestAccountByName(name: string): TestAccount;
-
-/**
- * Per-account `storageState` cache for Playwright.
- *
- * Better Auth applies a per-IP rate limit on `/api/auth/sign-in/email`
- * (~5 sign-ins / 60s / endpoint). A multiplayer suite that spins up
- * 5+ users per spec would hit the limit and start failing in non-obvious
- * ways. This module signs each account in *once*, persists the
- * resulting browser cookies + storage to disk, and reuses the file on
- * subsequent runs.
- *
- * Cache layout:
- *   ~/.deepspace/playwright-states/<sha256(email)>.json
- *
- * Validity: a cached file is reused if Playwright successfully loads it
- * AND the resulting context produces a non-anonymous session on the
- * target app. If validation fails, we fall back to a fresh sign-in and
- * overwrite the cache.
- */
-
-interface EnsureStorageStateOptions {
-    /** Max age of a cached state file before we re-sign-in. Default 7 days. */
-    maxAgeMs?: number;
-    /** Force a fresh sign-in even if the cache is fresh. */
-    force?: boolean;
-}
-/**
- * Ensure a Playwright `storageState` file exists for `account` and
- * return its path. Signs in once if the cache is missing, stale, or
- * `force: true`.
- */
-declare function ensureStorageState(browser: Browser, account: {
-    email: string;
-    password: string;
-}, baseURL: string, options?: EnsureStorageStateOptions): Promise<string>;
-/**
- * Convenience: open a fresh `BrowserContext` for `account` using the
- * cached storage state (signing in if needed). The caller is responsible
- * for closing the context.
- */
-declare function newSignedInContext(browser: Browser, account: {
-    email: string;
-    password: string;
-}, baseURL: string, options?: EnsureStorageStateOptions): Promise<BrowserContext>;
-/** Read a cached storageState file (mostly for debugging). */
-declare function readCachedState(email: string): unknown | null;
-/** Where the cache for `email` lives. Useful for diagnostics. */
-declare function getStatePathForEmail(email: string): string;
-
-export { type EnsureStorageStateOptions, type MultiplayerUser, type TestAccount, type UsersFixture, ensureStorageState, findTestAccountByName, getStatePathForEmail, loadAllTestAccounts, newSignedInContext, pickTestAccounts, readCachedState, test };