@archetypeai/ds-cli 0.3.9 → 0.3.11

package/bin.js

@@ -31,12 +31,16 @@ Create flags:
   --fonts / --no-fonts              Install internal fonts (default: prompt)
   --no-components                   Skip component installation (default: install all)
   --codeagent <cursor|claude|none>  Agent configuration (default: prompt)
+  --defaults                        Skip prompts, use sensible defaults
 
 Init flags:
   --pm <npm|pnpm|bun|yarn>          Package manager (default: auto-detect)
   --fonts / --no-fonts              Install internal fonts (default: prompt)
   --no-components                   Skip component installation (default: install all)
   --codeagent <cursor|claude|none>  Agent configuration (default: prompt)
+  --defaults                        Skip prompts, use sensible defaults
+
+Non-interactive shells (no TTY) automatically use defaults.
 
 Add targets:
   ds-ui-svelte                      Install all design system components

package/commands/create.js

@@ -8,10 +8,12 @@ import {
   installTokens,
   initShadcn,
   configureCss,
+  installLinting,
   installComponents,
   createDemoPage,
   installAgentConfig
 } from '../lib/scaffold-ds-svelte-project.js';
+import { isInteractive, DEFAULTS, logDefaultsNotice } from '../lib/is-interactive.js';
 
 // parse flags
 export function parseFlags(args) {
@@ -20,7 +22,8 @@ export function parseFlags(args) {
     framework: null,
     pm: null,
     components: true,
-    agent: null
+    agent: null,
+    defaults: false
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -33,6 +36,8 @@ export function parseFlags(args) {
       flags.components = false;
     } else if (arg === '--codeagent' && args[i + 1]) {
       flags.agent = args[++i];
+    } else if (arg === '--defaults') {
+      flags.defaults = true;
     } else if (!arg.startsWith('--') && !flags.name) {
       flags.name = arg;
     }
@@ -44,12 +49,17 @@ export function parseFlags(args) {
 // create a new project
 export async function create(args) {
   const flags = parseFlags(args);
+  const interactive = isInteractive(flags);
 
   p.intro('Create a new project using Archetype AI Design System.');
 
   // specify project name
   let name = flags.name;
   if (!name) {
+    if (!interactive) {
+      p.log.error('Project name is required. Usage: ds create <project-name>');
+      process.exit(1);
+    }
     name = await p.text({
       message: 'What is your project name?',
       placeholder: 'my-app',
@@ -87,26 +97,38 @@ export async function create(args) {
   // specify framework
   let framework = flags.framework;
   if (!framework) {
-    framework = await p.select({
-      message: 'Which framework?',
-      options: [{ value: 'svelte', label: 'SvelteKit', hint: 'Svelte 5 + Tailwind v4' }]
-    });
-    if (p.isCancel(framework)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
+    if (!interactive) {
+      framework = DEFAULTS.framework;
+    } else {
+      framework = await p.select({
+        message: 'Which framework?',
+        options: [{ value: 'svelte', label: 'SvelteKit', hint: 'Svelte 5 + Tailwind v4, default' }]
+      });
+      if (p.isCancel(framework)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+      }
     }
   }
 
   // specify package manager
   let pmName = flags.pm;
   if (!pmName) {
-    pmName = await p.select({
-      message: 'Which package manager?',
-      options: pmNames.map((n) => ({ value: n, label: n }))
-    });
-    if (p.isCancel(pmName)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
+    if (!interactive) {
+      pmName = DEFAULTS.pm;
+    } else {
+      pmName = await p.select({
+        message: 'Which package manager?',
+        options: pmNames.map((n) => ({
+          value: n,
+          label: n,
+          ...(n === DEFAULTS.pm && { hint: 'default' })
+        }))
+      });
+      if (p.isCancel(pmName)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+      }
     }
   }
   const pm = getPm(pmName);
@@ -122,13 +144,17 @@ export async function create(args) {
   const projectPath = resolve(targetDir, name);
 
   if (existsSync(projectPath)) {
-    const overwrite = await p.confirm({
-      message: `Directory "${name}" already exists. Continue anyway?`,
-      initialValue: false
-    });
-    if (p.isCancel(overwrite) || !overwrite) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
+    if (!interactive) {
+      p.log.warn(`Directory "${name}" already exists. Proceeding (non-interactive mode).`);
+    } else {
+      const overwrite = await p.confirm({
+        message: `Directory "${name}" already exists. Continue anyway?`,
+        initialValue: false
+      });
+      if (p.isCancel(overwrite) || !overwrite) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+      }
     }
   }
 
@@ -151,6 +177,9 @@ export async function create(args) {
   const includeFonts = false;
   configureCss(projectPath, includeFonts);
 
+  // set up linting and formatting
+  await installLinting(pm, projectPath);
+
   // install components
   if (flags.components) {
     try {
@@ -169,20 +198,33 @@ export async function create(args) {
   // specify agent config
   let agent = flags.agent;
   if (!agent) {
-    agent = await p.select({
-      message: 'Install AI agent configuration?',
-      options: [
-        { value: 'none', label: 'None' },
-        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
-        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules' }
-      ]
-    });
-    if (p.isCancel(agent)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
+    if (!interactive) {
+      agent = DEFAULTS.agent;
+    } else {
+      agent = await p.select({
+        message: 'Install AI agent configuration?',
+        options: [
+          { value: 'none', label: 'None' },
+          { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
+          { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules, default' }
+        ]
+      });
+      if (p.isCancel(agent)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+      }
     }
   }
 
+  // log defaults notice
+  if (!interactive) {
+    const applied = {};
+    if (!flags.framework) applied.framework = framework;
+    if (!flags.pm) applied.pm = pmName;
+    if (!flags.agent) applied.codeagent = agent;
+    logDefaultsNotice(applied);
+  }
+
   const validAgents = ['cursor', 'claude', 'none'];
   if (!validAgents.includes(agent)) {
     p.log.error(`Invalid --codeagent value "${agent}". Must be one of: ${validAgents.join(', ')}`);
@@ -203,6 +245,7 @@ export async function create(args) {
     `Framework:       ${framework}`,
     `Package Manager: ${pm.name}`,
     `Fonts:           ${includeFonts ? 'installed' : 'skipped'}`,
+    `Linting:         configured`,
     `Components:      ${flags.components ? 'all' : 'skipped'}`,
     `Agent Configuration:    ${agent}`
   ].join('\n');

package/commands/init.js

@@ -8,16 +8,19 @@ import {
   installTokens,
   initShadcn,
   prependCss,
+  installLinting,
   installComponents,
   installAgentConfig
 } from '../lib/scaffold-ds-svelte-project.js';
+import { isInteractive, DEFAULTS, logDefaultsNotice } from '../lib/is-interactive.js';
 
 // parse flags
 export function parseFlags(args) {
   const flags = {
     pm: null,
     components: true,
-    agent: null
+    agent: null,
+    defaults: false
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -28,6 +31,8 @@ export function parseFlags(args) {
       flags.components = false;
     } else if (arg === '--codeagent' && args[i + 1]) {
       flags.agent = args[++i];
+    } else if (arg === '--defaults') {
+      flags.defaults = true;
     }
   }
 
@@ -48,6 +53,7 @@ function hasTailwind(projectPath) {
 // initialize the design system in an existing project
 export async function init(args) {
   const flags = parseFlags(args);
+  const interactive = isInteractive(flags);
   const projectPath = process.cwd();
 
   // validate --pm flag
@@ -81,17 +87,33 @@ export async function init(args) {
     }
   }
   if (!pmName) {
-    pmName = await p.select({
-      message: 'Which package manager?',
-      options: pmNames.map((n) => ({ value: n, label: n }))
-    });
-    if (p.isCancel(pmName)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
+    if (!interactive) {
+      pmName = DEFAULTS.pm;
+    } else {
+      pmName = await p.select({
+        message: 'Which package manager?',
+        options: pmNames.map((n) => ({
+          value: n,
+          label: n,
+          ...(n === DEFAULTS.pm && { hint: 'default' })
+        }))
+      });
+      if (p.isCancel(pmName)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+      }
     }
   }
   const pm = getPm(pmName);
 
+  // log defaults notice
+  if (!interactive) {
+    const applied = {};
+    if (!flags.pm) applied.pm = pmName;
+    if (!flags.agent) applied.codeagent = DEFAULTS.agent;
+    logDefaultsNotice(applied);
+  }
+
   // verify package manager is installed
   if (!isPmInstalled(pmName)) {
     p.log.error(`${pmName} is not installed. Please install it first and try again.`);
@@ -120,6 +142,9 @@ export async function init(args) {
   const includeFonts = false;
   prependCss(projectPath, includeFonts);
 
+  // set up linting and formatting
+  await installLinting(pm, projectPath);
+
   // install components
   if (flags.components) {
     try {
@@ -138,17 +163,21 @@ export async function init(args) {
   // specify agent config
   let agent = flags.agent;
   if (!agent) {
-    agent = await p.select({
-      message: 'Install AI agent configuration?',
-      options: [
-        { value: 'none', label: 'None' },
-        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
-        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules' }
-      ]
-    });
-    if (p.isCancel(agent)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
+    if (!interactive) {
+      agent = DEFAULTS.agent;
+    } else {
+      agent = await p.select({
+        message: 'Install AI agent configuration?',
+        options: [
+          { value: 'none', label: 'None' },
+          { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
+          { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules, default' }
+        ]
+      });
+      if (p.isCancel(agent)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+      }
     }
   }
 
@@ -167,6 +196,7 @@ export async function init(args) {
     `Location:        ${projectPath}`,
     `Package Manager: ${pm.name}`,
     `Fonts:           ${includeFonts ? 'installed' : 'skipped'}`,
+    `Linting:         configured`,
     `Components:      ${flags.components ? 'all' : 'skipped'}`,
     `Agent Config:    ${agent}`
   ].join('\n');

package/files/AGENTS.md

@@ -28,7 +28,6 @@ Standard Tailwind is fine for:
 
 - Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
 - Layout: `flex`, `grid`, `absolute`, `relative`
-- One-off colors: gradients, illustrations, custom accents
 
 ## CSS Import Order
 
@@ -49,15 +48,32 @@ Standard Tailwind is fine for:
 
 Read these when relevant to your task:
 
-- `@skills/apply-ds` - setup tokens in new project
+- `@skills/apply-ds` - apply DS tokens, components, and patterns to an existing demo
 - `@skills/build-pattern` - create composite patterns from primitives
 - `@skills/setup-chart` - set up charts with layerchart
 - `@skills/create-dashboard` - scaffold a full-viewport dashboard with menubar and panels
 - `@skills/fix-accessibility` - audit and fix a11y issues
 - `@skills/fix-metadata` - update page titles, favicons, and OG tags
 - `@skills/deploy-worker` - deploy SvelteKit projects to Cloudflare Workers
-- `@skills/explain-code` - explain code with structure and traced execution
+- `@skills/embedding-from-file` - run an Embedding Lens by streaming sensor data from a CSV file
+- `@skills/embedding-from-sensor` - run an Embedding Lens by streaming real-time data from a physical sensor
+- `@skills/embedding-upload` - run an Embedding Lens by uploading a CSV file for server-side processing
+- `@skills/newton-activity-monitor-lens-on-video` - analyze uploaded video files using Newton's activity monitor lens
+- `@skills/newton-camera-frame-analysis` - live webcam frame analysis using Newton's vision model
+- `@skills/newton-direct-query` - simple direct query to Newton model using the /query API endpoint
+- `@skills/newton-machine-state-from-file` - run a Machine State Lens by streaming sensor data from a CSV file
+- `@skills/newton-machine-state-from-sensor` - run a Machine State Lens by streaming real-time data from a physical sensor
+- `@skills/newton-machine-state-upload` - run a Machine State Lens by uploading a CSV file for server-side processing
 
 ## Rules
 
 See `@rules/` for comprehensive guidance on design principles, components, styling, charts, and linting.
+
+- `@rules/accessibility` — a11y guidelines and ARIA patterns
+- `@rules/charts` — chart setup, layerchart conventions, data visualization
+- `@rules/components` — component API patterns, props, variants, slots
+- `@rules/design-principles` — visual design language, spacing, typography
+- `@rules/frontend-architecture` — component decomposition, page composition, API logic extraction
+- `@rules/linting` — linting and formatting rules
+- `@rules/state` — state management with Svelte 5 runes
+- `@rules/styling` — Tailwind v4, semantic tokens, theming

package/files/CLAUDE.md

@@ -28,7 +28,6 @@ Standard Tailwind is fine for:
 
 - Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
 - Layout: `flex`, `grid`, `absolute`, `relative`
-- One-off colors: gradients, illustrations, custom accents
 
 ## CSS Import Order
 
@@ -47,17 +46,36 @@ Standard Tailwind is fine for:
 
 ## Skills
 
+**Skill composition:** When building a demo that uses a Newton or Embedding API skill, also consult `@skills/create-dashboard` for dashboard layouts and `@skills/build-pattern` for extracting components. Only include chart components (SensorChart, ScatterChart) if the user's request involves time-series or explicitly mentions charts.
+
 Read these when relevant to your task:
 
-- `@skills/apply-ds` - setup tokens in new project
+- `@skills/apply-ds` - apply DS tokens, components, and patterns to an existing demo
 - `@skills/build-pattern` - create composite patterns from primitives
 - `@skills/setup-chart` - set up charts with layerchart
 - `@skills/create-dashboard` - scaffold a full-viewport dashboard with menubar and panels
 - `@skills/fix-accessibility` - audit and fix a11y issues
 - `@skills/fix-metadata` - update page titles, favicons, and OG tags
 - `@skills/deploy-worker` - deploy SvelteKit projects to Cloudflare Workers
-- `@skills/explain-code` - explain code with structure and traced execution
+- `@skills/embedding-from-file` - run an Embedding Lens by streaming sensor data from a CSV file
+- `@skills/embedding-from-sensor` - run an Embedding Lens by streaming real-time data from a physical sensor
+- `@skills/embedding-upload` - run an Embedding Lens by uploading a CSV file for server-side processing
+- `@skills/newton-activity-monitor-lens-on-video` - analyze uploaded video files using Newton's activity monitor lens
+- `@skills/newton-camera-frame-analysis` - live webcam frame analysis using Newton's vision model
+- `@skills/newton-direct-query` - simple direct query to Newton model using the /query API endpoint
+- `@skills/newton-machine-state-from-file` - run a Machine State Lens by streaming sensor data from a CSV file
+- `@skills/newton-machine-state-from-sensor` - run a Machine State Lens by streaming real-time data from a physical sensor
+- `@skills/newton-machine-state-upload` - run a Machine State Lens by uploading a CSV file for server-side processing
 
 ## Rules
 
 See `@rules/` for comprehensive guidance on design principles, components, styling, charts, and linting.
+
+- `@rules/accessibility` — a11y guidelines and ARIA patterns
+- `@rules/charts` — chart setup, layerchart conventions, data visualization
+- `@rules/components` — component API patterns, props, variants, slots
+- `@rules/design-principles` — visual design language, spacing, typography
+- `@rules/frontend-architecture` — component decomposition, page composition, API logic extraction
+- `@rules/linting` — linting and formatting rules
+- `@rules/state` — state management with Svelte 5 runes
+- `@rules/styling` — Tailwind v4, semantic tokens, theming

package/files/rules/accessibility.md

@@ -205,10 +205,59 @@ For custom interactive elements, ensure:
 >
 ```
 
+## Page Structure
+
+### Skip Link
+
+Every page should have a skip link as the first focusable element:
+
+```svelte
+<a
+  href="#main-content"
+  class="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-50 focus:rounded-md focus:bg-background focus:px-4 focus:py-2 focus:text-foreground focus:ring-2 focus:ring-ring"
+>
+  Skip to content
+</a>
+
+<main id="main-content">
+  <!-- page content -->
+</main>
+```
+
+### Semantic Landmarks
+
+Use semantic HTML elements instead of generic `<div>` wrappers:
+
+```svelte
+<!-- Before -->
+<div class="header">...</div>
+<div class="nav">...</div>
+<div class="content">...</div>
+
+<!-- After -->
+<header>...</header>
+<nav>...</nav>
+<main id="main-content">...</main>
+```
+
+### Heading Hierarchy
+
+Every page needs an `<h1>`. If the visual design doesn't include one, add it as screen-reader-only:
+
+```svelte
+<h1 class="sr-only">Dashboard</h1>
+```
+
+Never skip heading levels (e.g. `<h1>` → `<h3>`). Use the correct level for the document outline.
+
 ## Checklist
 
 When building components, verify:
 
+- [ ] Page has a skip-to-content link as the first focusable element
+- [ ] Page uses semantic landmarks (`<main>`, `<header>`, `<nav>`)
+- [ ] Page has an `<h1>` (visible or `sr-only`)
+- [ ] Heading hierarchy doesn't skip levels
 - [ ] Icon-only buttons have `aria-label`
 - [ ] Decorative icons have `aria-hidden="true"`
 - [ ] Interactive groups have `aria-label`

package/files/rules/frontend-architecture.md

@@ -0,0 +1,77 @@
+---
+paths:
+  - '**/routes/**/*.svelte'
+  - '**/+page.svelte'
+  - '**/+layout.svelte'
+---
+
+# Frontend Architecture
+
+When building a page that involves more than a simple static layout, decompose it into components rather than writing a monolithic `+page.svelte`.
+
+## When to extract a component
+
+Extract a component when a section of UI has:
+
+- 3+ primitives composed together (Card + Badge + Button = a status card)
+- Its own reactive state (`$state`, `$derived`)
+- Potential for reuse across pages or skills
+
+Common extraction candidates: media inputs, status displays, result/summary views, streaming logs, file upload flows.
+
+## Gold-standard references
+
+The project includes pattern components that demonstrate these conventions. Study them before building new ones:
+
+- `$lib/components/ui/VideoPlayer.svelte` — media playback with controls, composes Card + AspectRatio + Button + Slider
+- `$lib/components/ui/ExpandableLog.svelte` — streaming log display, composes Collapsible + Item + Badge
+- `$lib/components/ui/StatusBadge.svelte` — health indicator with derived state, composes Badge + Avatar
+- `$lib/components/ui/HealthscoreCard.svelte` — score card with derived state, composes Card sub-components
+- `$lib/components/ui/Menubar.svelte` — branded header with snippet slots
+
+Check if an existing pattern fits before building a new one. Use `@skills/build-pattern` to create new patterns that follow these same conventions.
+
+## Component conventions
+
+Follow `@rules/components` for the full conventions. The essentials:
+
+- `let { class: className, ...restProps } = $props();`
+- `cn()` for all class merging — never raw string concatenation
+- `$derived` for computed state
+- Spread `...restProps` on the root element
+- Compose from DS primitives (Card, Badge, Button, etc.) — not raw HTML
+
+## Page-level orchestration
+
+`+page.svelte` is the orchestrator. It should:
+
+- Own flow state (status, session IDs, error messages)
+- Import and compose child components
+- Pass data down via props
+- Handle top-level layout (using `@skills/create-dashboard` for dashboard layouts)
+
+Components should be presentational where possible — receive data via props, emit events up.
+
+## API and streaming logic extraction
+
+SSE consumers, fetch wrappers, polling loops, and data transforms belong in a utility file, not inline in components or pages:
+
+```
+src/lib/api/activity-monitor.js   — SSE + session management
+src/lib/api/machine-state.js      — streaming + windowing
+src/lib/api/embeddings.js         — upload + embedding extraction
+```
+
+This keeps components focused on rendering and makes API logic testable and reusable.
+
+## Streaming UI
+
+For skills that stream results (SSE, polling), prefer:
+
+- Progressive rendering — show results as they arrive, don't wait for completion
+- Live counters or progress indicators
+- Auto-scrolling log views (reference ExpandableLog pattern)
+
+## Override clause
+
+If the user explicitly requests a single-file prototype, a minimal example, or specifies a different structure, follow their instruction. These guidelines apply to production-quality demos, not quick experiments.