@soederpop/luca 0.0.2

package/src/node/features/nlp.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod'
+import { Feature, features } 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
+
+  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 features.register('nlp', NLP)

package/src/node/features/opener.ts

@@ -0,0 +1,166 @@
+import { features, 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
+
+  /**
+   * 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 = process.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): Promise<void> {
+    const proc = this.container.proc
+
+    if (platform === 'darwin') {
+      await proc.spawnAndCapture('open', ['-a', 'Google Chrome', url])
+    } else if (platform === 'win32') {
+      await proc.spawnAndCapture('cmd', ['/c', 'start', 'chrome', url])
+    } else {
+      // Linux - try google-chrome, then chromium, then fall back to xdg-open
+      try {
+        await proc.spawnAndCapture('google-chrome', [url])
+      } catch {
+        try {
+          await proc.spawnAndCapture('chromium', [url])
+        } catch {
+          await proc.spawnAndCapture('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 = process.platform
+    const proc = this.container.proc
+
+    if (platform === 'darwin') {
+      await proc.spawnAndCapture('open', ['-a', name])
+    } else if (platform === 'win32') {
+      await proc.spawnAndCapture('cmd', ['/c', 'start', '', name])
+    } else {
+      await proc.spawnAndCapture(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('code', [path])
+    } catch {
+      if (process.platform === 'darwin') {
+        await proc.spawnAndCapture('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('cursor', [path])
+    } catch {
+      if (process.platform === 'darwin') {
+        await proc.spawnAndCapture('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('open', [target])
+    } else if (platform === 'win32') {
+      await proc.spawnAndCapture('cmd', ['/c', 'start', '', target])
+    } else {
+      await proc.spawnAndCapture('xdg-open', [target])
+    }
+  }
+}
+
+declare module '../../feature' {
+  interface AvailableFeatures {
+    opener: typeof Opener
+  }
+}
+
+export default features.register("opener", Opener)

package/src/node/features/os.ts

@@ -0,0 +1,157 @@
+import { Feature, features } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import os from 'os'
+
+/**
+ * The OS feature provides access to operating system utilities and information.
+ * 
+ * This feature wraps Node.js's built-in `os` module and provides convenient
+ * getters for system information like architecture, platform, directories,
+ * network interfaces, and hardware details.
+ * 
+ * @example
+ * ```typescript
+ * const osInfo = container.feature('os')
+ * 
+ * console.log(`Platform: ${osInfo.platform}`)
+ * console.log(`Architecture: ${osInfo.arch}`)
+ * console.log(`CPU cores: ${osInfo.cpuCount}`)
+ * console.log(`Home directory: ${osInfo.homedir}`)
+ * ```
+ * 
+ * @extends Feature
+ */
+export class OS extends Feature {
+  static override shortcut = 'features.os' as const
+  static override stateSchema = FeatureStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+  
+  /**
+   * Gets the operating system CPU architecture.
+   * 
+   * @returns {string} The CPU architecture (e.g., 'x64', 'arm64', 'arm', 'ia32')
+   * 
+   * @example
+   * ```typescript
+   * const arch = os.arch
+   * console.log(`Running on ${arch} architecture`)
+   * ```
+   */
+  get arch() {
+    return os.arch()
+  }
+  
+  /**
+   * Gets the operating system's default directory for temporary files.
+   * 
+   * @returns {string} The path to the temporary directory
+   * 
+   * @example
+   * ```typescript
+   * const tempDir = os.tmpdir
+   * console.log(`Temp directory: ${tempDir}`)
+   * ```
+   */
+  get tmpdir() {
+    return os.tmpdir()
+  }
+  
+  /**
+   * Gets the current user's home directory path.
+   * 
+   * @returns {string} The path to the user's home directory
+   * 
+   * @example
+   * ```typescript
+   * const home = os.homedir
+   * console.log(`User home: ${home}`)
+   * ```
+   */
+  get homedir() {
+    return os.homedir()
+  }
+  
+  /**
+   * Gets the number of logical CPU cores available on the system.
+   * 
+   * @returns {number} The number of CPU cores
+   * 
+   * @example
+   * ```typescript
+   * const cores = os.cpuCount
+   * console.log(`System has ${cores} CPU cores`)
+   * ```
+   */
+  get cpuCount() {
+    return os.cpus().length
+  }
+
+  /**
+   * Gets the hostname of the operating system.
+   * 
+   * @returns {string} The system hostname
+   * 
+   * @example
+   * ```typescript
+   * const hostname = os.hostname
+   * console.log(`Hostname: ${hostname}`)
+   * ```
+   */
+  get hostname() {
+    return os.hostname()
+  }
+
+  /**
+   * Gets the operating system platform.
+   * 
+   * @returns {string} The platform identifier (e.g., 'darwin', 'linux', 'win32')
+   * 
+   * @example
+   * ```typescript
+   * const platform = os.platform
+   * if (platform === 'darwin') {
+   *   console.log('Running on macOS')
+   * }
+   * ```
+   */
+  get platform() {
+    return os.platform()
+  }
+  
+  /**
+   * Gets information about the system's network interfaces.
+   * 
+   * @returns {NodeJS.Dict<os.NetworkInterfaceInfo[]>} Object containing network interface details
+   * 
+   * @example
+   * ```typescript
+   * const interfaces = os.networkInterfaces
+   * Object.keys(interfaces).forEach(name => {
+   *   console.log(`Interface ${name}:`, interfaces[name])
+   * })
+   * ```
+   */
+  get networkInterfaces() {
+    return os.networkInterfaces()
+  }
+  
+  /**
+   * Gets an array of MAC addresses for non-internal IPv4 network interfaces.
+   * 
+   * This filters the network interfaces to only include external IPv4 interfaces
+   * and returns their MAC addresses, which can be useful for system identification.
+   * 
+   * @returns {string[]} Array of MAC addresses for external IPv4 interfaces
+   * 
+   * @example
+   * ```typescript
+   * const macAddresses = os.macAddresses
+   * console.log(`External MAC addresses: ${macAddresses.join(', ')}`)
+   * ```
+   */
+  get macAddresses() : string[] {
+    return Object.values(this.networkInterfaces).flat().filter(v => typeof v !== 'undefined' && v.internal === false && v.family === 'IPv4').map(v => v?.mac!).filter(Boolean)
+  }
+}
+
+export default features.register('os', OS)