luca 2.0.0 → 3.0.0

package/src/node/features/nlp.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod'
+import { Feature } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import compromise from 'compromise'
+import winkNLP from 'wink-nlp'
+import model from 'wink-eng-lite-web-model'
+
+export const NLPStateSchema = FeatureStateSchema.extend({
+  parseCalls: z.number().default(0).describe('Total parse() invocations'),
+  analyzeCalls: z.number().default(0).describe('Total analyze() invocations'),
+})
+
+export const NLPOptionsSchema = FeatureOptionsSchema.extend({})
+
+export const ParsedCommandSchema = z.object({
+  intent: z.string().nullable().describe('The normalized verb/action (infinitive form)'),
+  target: z.string().nullable().describe('The primary noun/object'),
+  subject: z.string().nullable().describe('Secondary noun from prepositional phrase'),
+  modifiers: z.array(z.string()).describe('Adjectives and adverbs'),
+  raw: z.string().describe('Original input text'),
+})
+
+export const AnalysisSchema = z.object({
+  tokens: z.array(z.object({
+    value: z.string(),
+    pos: z.string(),
+  })).describe('POS-tagged tokens (Universal POS tagset)'),
+  entities: z.array(z.object({
+    value: z.string(),
+    type: z.string(),
+  })).describe('Recognized named entities'),
+  raw: z.string(),
+})
+
+export type ParsedCommand = z.infer<typeof ParsedCommandSchema>
+export type Analysis = z.infer<typeof AnalysisSchema>
+
+/**
+ * The NLP feature provides natural language processing utilities for parsing
+ * utterances into structured data. Combines two complementary libraries:
+ *
+ * - **compromise**: Verb normalization (toInfinitive), POS pattern matching
+ * - **wink-nlp**: High-accuracy POS tagging (~95%), named entity recognition
+ *
+ * Three methods at increasing levels of detail:
+ * - `parse()` — compromise-powered quick structure + verb normalization
+ * - `analyze()` — wink-powered high-accuracy POS + entity extraction
+ * - `understand()` — combined parse + analyze merged
+ *
+ * @example
+ * ```typescript
+ * const nlp = container.feature('nlp', { enable: true })
+ *
+ * nlp.parse("draw a diagram of the auth flow")
+ * // { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+ *
+ * nlp.analyze("meet john at 3pm about the deployment")
+ * // { tokens: [{value:"meet",pos:"VERB"}, ...], entities: [{value:"john",type:"PERSON"}, ...] }
+ *
+ * nlp.understand("draw a diagram of the auth flow")
+ * // { intent, target, subject, modifiers, tokens, entities, raw }
+ * ```
+ */
+export class NLP extends Feature<z.infer<typeof NLPStateSchema>, z.infer<typeof NLPOptionsSchema>> {
+  static override shortcut = 'features.nlp' as const
+  static override stateSchema = NLPStateSchema
+  static override optionsSchema = NLPOptionsSchema
+  static { Feature.register(this, 'nlp') }
+
+  private _wink?: ReturnType<typeof winkNLP>
+
+  /** Lazily initializes the wink-nlp instance on first use. */
+  private get wink(): ReturnType<typeof winkNLP> {
+    if (!this._wink) {
+      this._wink = winkNLP(model)
+    }
+    return this._wink
+  }
+
+  /**
+   * Parse an utterance into structured command data using compromise.
+   * Extracts intent (normalized verb), target noun, prepositional subject, and modifiers.
+   *
+   * @param text - The raw utterance to parse
+   * @returns Parsed command structure with intent, target, subject, modifiers
+   *
+   * @example
+   * ```typescript
+   * nlp.parse("open the terminal")
+   * // { intent: "open", target: "terminal", subject: null, modifiers: [], raw: "open the terminal" }
+   *
+   * nlp.parse("draw a diagram of the auth flow")
+   * // { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+   * ```
+   */
+  parse(text: string): ParsedCommand {
+    // Use a separate doc for verb normalization (toInfinitive modifies terms in place)
+    const verbDoc = compromise(text)
+    const verbs = verbDoc.verbs().toInfinitive()
+    const verbArray = (verbs as any).out('array') as string[]
+    // First verb phrase — take just the root verb word
+    const firstVerb = verbArray.length > 0 ? verbArray[0] : null
+    const intent = firstVerb
+      ? firstVerb.trim().split(/\s+/)[0]!.toLowerCase()
+      : null
+
+    // Fresh doc for structure extraction
+    const doc = compromise(text)
+
+    let target: string | null = null
+    let subject: string | null = null
+
+    // Try prepositional structure: verb [det] noun+ prep [det] noun+
+    const prepMatch = doc.match('#Verb #Determiner? #Noun+ (of|about|for|with) #Determiner? #Noun+')
+    if ((prepMatch as any).found) {
+      // Nouns before the preposition
+      const beforePrep = doc.match('#Verb #Determiner? #Noun+ (of|about|for|with)')
+      const targetNouns = (beforePrep as any).match('#Noun+')
+      target = targetNouns.text().trim() || null
+
+      // Nouns after the preposition
+      const afterPrep = doc.match('(of|about|for|with) #Determiner? #Noun+')
+      const subjectNouns = (afterPrep as any).match('#Noun+')
+      subject = subjectNouns.text().trim() || null
+    } else {
+      // Simple: verb [det] noun+
+      const simpleMatch = doc.match('#Verb #Determiner? #Noun+')
+      if ((simpleMatch as any).found) {
+        const targetNouns = (simpleMatch as any).match('#Noun+')
+        target = targetNouns.text().trim() || null
+      }
+    }
+
+    // Modifiers: adjectives and adverbs
+    const adjectives = (doc as any).adjectives().out('array') as string[]
+    const adverbs = (doc as any).adverbs().out('array') as string[]
+    const modifiers = [...new Set([...adjectives, ...adverbs])].filter(Boolean)
+
+    this.state.set('parseCalls', (this.state.get('parseCalls') || 0) + 1)
+
+    return { intent, target, subject, modifiers, raw: text }
+  }
+
+  /**
+   * Analyze text with high-accuracy POS tagging and named entity recognition using wink-nlp.
+   *
+   * @param text - The text to analyze
+   * @returns Token-level POS tags (Universal POS tagset) and named entities
+   *
+   * @example
+   * ```typescript
+   * nlp.analyze("meet john at 3pm about the deployment")
+   * // { tokens: [{value:"meet",pos:"VERB"}, {value:"john",pos:"PROPN"}, ...],
+   * //   entities: [{value:"john",type:"PERSON"}, {value:"3pm",type:"TIME"}],
+   * //   raw: "meet john at 3pm about the deployment" }
+   * ```
+   */
+  analyze(text: string): Analysis {
+    const doc = this.wink.readDoc(text)
+    const its = this.wink.its
+
+    // Get tokens with POS tags
+    const values = doc.tokens().out(its.value) as string[]
+    const posTags = doc.tokens().out(its.pos) as string[]
+
+    const tokens = values.map((value, i) => ({
+      value,
+      pos: posTags[i] || 'X',
+    }))
+
+    // Get entities with types
+    const entities: Array<{ value: string; type: string }> = []
+    doc.entities().each((entity: any) => {
+      entities.push({
+        value: entity.out(),
+        type: entity.out((its as any).type) || 'UNKNOWN',
+      })
+    })
+
+    this.state.set('analyzeCalls', (this.state.get('analyzeCalls') || 0) + 1)
+
+    return { tokens, entities, raw: text }
+  }
+
+  /**
+   * Full understanding: combines compromise parsing with wink-nlp analysis.
+   * Returns intent, target, subject, modifiers (from parse) plus tokens and entities (from analyze).
+   *
+   * @param text - The text to understand
+   * @returns Combined parse + analyze result
+   *
+   * @example
+   * ```typescript
+   * nlp.understand("draw a diagram of the auth flow")
+   * // { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [],
+   * //   tokens: [{value:"draw",pos:"VERB"}, ...], entities: [...], raw: "..." }
+   * ```
+   */
+  understand(text: string): ParsedCommand & Analysis {
+    const parsed = this.parse(text)
+    const analysis = this.analyze(text)
+
+    // parse() and analyze() each increment their counters,
+    // so we correct the double-count by decrementing once
+    this.state.set('parseCalls', (this.state.get('parseCalls') || 1) - 1)
+    this.state.set('analyzeCalls', (this.state.get('analyzeCalls') || 1) - 1)
+
+    return { ...parsed, ...analysis }
+  }
+}
+
+export default NLP

package/src/node/features/opener.ts

@@ -0,0 +1,180 @@
+import { Feature } from "../feature.js";
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+
+/**
+ * The Opener feature opens files, URLs, desktop applications, and code editors.
+ *
+ * HTTP/HTTPS URLs are opened in Google Chrome. Desktop apps can be launched by name.
+ * VS Code and Cursor can be opened to a specific path. All other paths are opened
+ * with the platform's default handler (e.g. Preview for images, Finder for folders).
+ *
+ * @example
+ * ```typescript
+ * const opener = container.feature('opener')
+ *
+ * // Open a URL in Chrome
+ * await opener.open('https://www.google.com')
+ *
+ * // Open a file with the default application
+ * await opener.open('/path/to/image.png')
+ *
+ * // Open a desktop application
+ * await opener.app('Slack')
+ *
+ * // Open VS Code at a project path
+ * await opener.code('/Users/jon/projects/my-app')
+ *
+ * // Open Cursor at a project path
+ * await opener.cursor('/Users/jon/projects/my-app')
+ * ```
+ *
+ * @extends Feature
+ */
+export class Opener extends Feature {
+  static override shortcut = "features.opener" as const
+  static override description = "Opens files, URLs, desktop apps, and code editors"
+  static override stateSchema = FeatureStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+  static { Feature.register(this, 'opener') }
+
+  private _binCache: Record<string, string> = {}
+
+  /** Resolve a binary path via `which`, caching the result. */
+  private resolveBin(name: string): string {
+    if (this._binCache[name]) return this._binCache[name]
+    try {
+      this._binCache[name] = this.container.proc.exec(`which ${name}`).trim()
+    } catch {
+      this._binCache[name] = name
+    }
+    return this._binCache[name]
+  }
+
+  /**
+   * Opens a path or URL with the appropriate application.
+   *
+   * HTTP and HTTPS URLs are opened in Google Chrome.
+   * Everything else is opened with the system default handler via `open` (macOS).
+   *
+   * @param {string} target - A URL or file path to open
+   * @returns {Promise<void>}
+   */
+  async open(target: string): Promise<void> {
+    const isUrl = /^https?:\/\//i.test(target)
+    const platform = this.container.os.platform 
+
+    if (isUrl) {
+      console.log(`Opening ${target} in Chrome`)
+      await this.openInChrome(target, platform)
+    } else {
+      await this.openDefault(target, platform)
+    }
+  }
+
+  private async openInChrome(url: string, platform: string = this.container.os.platform): Promise<void> {
+    const proc = this.container.proc
+
+    if (platform === 'darwin') {
+      await proc.spawnAndCapture(this.resolveBin('open'), ['-a', 'Google Chrome', url])
+    } else if (platform === 'win32') {
+      await proc.spawnAndCapture(this.resolveBin('cmd'), ['/c', 'start', 'chrome', url])
+    } else {
+      // Linux - try google-chrome, then chromium, then fall back to xdg-open
+      try {
+        await proc.spawnAndCapture(this.resolveBin('google-chrome'), [url])
+      } catch {
+        try {
+          await proc.spawnAndCapture(this.resolveBin('chromium'), [url])
+        } catch {
+          await proc.spawnAndCapture(this.resolveBin('xdg-open'), [url])
+        }
+      }
+    }
+  }
+
+  /**
+   * Opens a desktop application by name.
+   *
+   * On macOS, uses `open -a` to launch the app. On Windows, uses `start`.
+   * On Linux, attempts to run the lowercase app name as a command.
+   *
+   * @param {string} name - The application name (e.g. "Slack", "Finder", "Safari")
+   * @returns {Promise<void>}
+   */
+  async app(name: string): Promise<void> {
+    const platform = this.container.os.platform
+    const proc = this.container.proc
+
+    if (platform === 'darwin') {
+      await proc.spawnAndCapture(this.resolveBin('open'), ['-a', name])
+    } else if (platform === 'win32') {
+      await proc.spawnAndCapture(this.resolveBin('cmd'), ['/c', 'start', '', name])
+    } else {
+      await proc.spawnAndCapture(this.resolveBin(name.toLowerCase()), [])
+    }
+  }
+
+  /**
+   * Opens VS Code at the specified path.
+   *
+   * Uses the `code` CLI command. Falls back to `open -a "Visual Studio Code"` on macOS.
+   *
+   * @param {string} [path="."] - The file or folder path to open
+   * @returns {Promise<void>}
+   */
+  async code(path: string = "."): Promise<void> {
+    const proc = this.container.proc
+
+    try {
+      await proc.spawnAndCapture(this.resolveBin('code'), [path])
+    } catch {
+      if (this.container.os.platform === 'darwin') {
+        await proc.spawnAndCapture(this.resolveBin('open'), ['-a', 'Visual Studio Code', path])
+      } else {
+        throw new Error('VS Code CLI (code) not found. Install it from VS Code: Command Palette > "Shell Command: Install code command in PATH"')
+      }
+    }
+  }
+
+  /**
+   * Opens Cursor at the specified path.
+   *
+   * Uses the `cursor` CLI command. Falls back to `open -a "Cursor"` on macOS.
+   *
+   * @param {string} [path="."] - The file or folder path to open
+   * @returns {Promise<void>}
+   */
+  async cursor(path: string = "."): Promise<void> {
+    const proc = this.container.proc
+
+    try {
+      await proc.spawnAndCapture(this.resolveBin('cursor'), [path])
+    } catch {
+      if (this.container.os.platform === 'darwin') {
+        await proc.spawnAndCapture(this.resolveBin('open'), ['-a', 'Cursor', path])
+      } else {
+        throw new Error('Cursor CLI (cursor) not found. Install it from Cursor: Command Palette > "Shell Command: Install cursor command in PATH"')
+      }
+    }
+  }
+
+  private async openDefault(target: string, platform: string): Promise<void> {
+    const proc = this.container.proc
+
+    if (platform === 'darwin') {
+      await proc.spawnAndCapture(this.resolveBin('open'), [target])
+    } else if (platform === 'win32') {
+      await proc.spawnAndCapture(this.resolveBin('cmd'), ['/c', 'start', '', target])
+    } else {
+      await proc.spawnAndCapture(this.resolveBin('xdg-open'), [target])
+    }
+  }
+}
+
+declare module '../../feature' {
+  interface AvailableFeatures {
+    opener: typeof Opener
+  }
+}
+
+export default Opener