@acpfx/core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @acpfx/core
 
+## 0.4.0
+
+### Minor Changes
+
+- 0e6838e: Add local on-device STT and TTS nodes (no API keys required). Introduces --acpfx-\* flag convention with setup phase for first-time model downloads, dynamic release pipeline with dual CPU/CUDA builds, MLX acceleration on Mac, and TUI improvements for speech event display.
+
+## 0.3.0
+
+### Minor Changes
+
+- a0320a1: Add manifest argument/env schema, config system, pipeline resolver, and onboarding TUI
+
+  - **Manifest schema**: Node manifests now declare typed `arguments` (string/number/boolean with defaults, enums, required) and `env` var requirements. Codegen produces TypeScript types + Zod schemas.
+  - **All 12 node manifests updated** with arguments and env declarations derived from source code audit.
+  - **Build-time validation**: `scripts/validate-manifests.ts` validates against generated Zod schema. Orchestrator validates settings at startup.
+  - **Config system**: `~/.acpfx/config.json` (global) and `.acpfx/config.json` (project) with env var layering. New CLI: `acpfx config`, `acpfx config set/get`.
+  - **Pipeline resolver**: `acpfx run [name]` resolves pipelines from .acpfx/pipelines/, ~/.acpfx/pipelines/, or bundled examples. `acpfx pipelines` lists available pipelines.
+  - **Onboarding TUI**: `acpfx onboard` for interactive pipeline creation from templates or scratch. Auto-triggered on first `acpfx run` with no default pipeline.
+
+### Patch Changes
+
+- 79c6694: Consolidate mic-aec and mic-sox into unified mic-speaker node
+
+  - **Remove `node-mic-aec` and `node-mic-sox`**: Replaced by the native `node-mic-speaker` package with built-in AEC support.
+  - **Add `node-mic-speaker`**: Rust-based mic capture + speaker output with acoustic echo cancellation in a single node.
+  - **Simplify pipeline configs**: Remove deprecated AEC/sysvoice pipeline variants; update remaining configs to use `@acpfx/mic-speaker`.
+  - **Update audio-player**: Streamline to work with the new mic-speaker node.
+  - **Update orchestrator**: Onboarding, templates, and node runner adjusted for consolidated mic node.
+  - **Update tests**: Reflect removed packages and new node structure.
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acpfx/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/acpfx-flags.ts

@@ -0,0 +1,51 @@
+/**
+ * acpfx flag protocol types and handler.
+ *
+ * All orchestrator-reserved flags use the `--acpfx-` prefix.
+ * Nodes that receive an unrecognized `--acpfx-*` flag should emit
+ * an UnsupportedFlagResponse and exit 0 (forward compatibility).
+ */
+
+import { z } from "zod";
+
+// ---- Types ----
+
+/** Response from `--acpfx-setup-check`. */
+export interface SetupCheckResponse {
+  needed: boolean;
+  description?: string;
+}
+
+/** Progress line from `--acpfx-setup` (NDJSON on stdout). */
+export type SetupProgress =
+  | { type: "progress"; message: string; pct?: number }
+  | { type: "complete"; message: string }
+  | { type: "error"; message: string };
+
+/** Response for unrecognized `--acpfx-*` flags (forward compatibility). */
+export interface UnsupportedFlagResponse {
+  unsupported: boolean;
+  flag: string;
+}
+
+// ---- Zod Schemas ----
+
+export const SetupCheckResponseSchema = z.object({
+  needed: z.boolean(),
+  description: z.string().optional(),
+});
+
+export const SetupProgressSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("progress"),
+    message: z.string(),
+    pct: z.number().optional(),
+  }),
+  z.object({ type: z.literal("complete"), message: z.string() }),
+  z.object({ type: z.literal("error"), message: z.string() }),
+]);
+
+export const UnsupportedFlagResponseSchema = z.object({
+  unsupported: z.boolean(),
+  flag: z.string(),
+});

package/src/manifest.ts

@@ -1,32 +1,130 @@
 /**
- * Manifest utilities for acpfx nodes.
+ * Manifest types, Zod schemas, and acpfx flag handling for nodes.
  *
- * Call `handleManifestFlag()` at the top of your node's entry point.
- * If `--manifest` is in argv, it prints the manifest as JSON and exits.
+ * Call `handleAcpfxFlags()` at the top of your node's entry point.
+ * It handles all `--acpfx-*` convention flags:
+ *   --acpfx-manifest       Print manifest JSON and exit
+ *   --acpfx-setup-check    Print {"needed": false} and exit (TS nodes don't need setup)
+ *   --acpfx-*  (unknown)   Print {"unsupported": true, "flag": "..."} and exit
  */
 
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { z } from "zod";
+
+// ---- Manifest Types ----
+
+export type ArgumentType = "string" | "number" | "boolean";
+
+export interface ManifestArgument {
+  type: ArgumentType;
+  default?: unknown;
+  description?: string;
+  required?: boolean;
+  enum?: unknown[];
+}
+
+export interface ManifestEnvField {
+  required?: boolean;
+  description?: string;
+}
 
 export interface NodeManifest {
   name: string;
   description?: string;
   consumes: string[];
   emits: string[];
+  arguments?: Record<string, ManifestArgument>;
+  additional_arguments?: boolean;
+  env?: Record<string, ManifestEnvField>;
 }
 
+// ---- Manifest Zod Schemas ----
+
+export const ArgumentTypeSchema = z.enum(["string", "number", "boolean"]);
+
+export const ManifestArgumentSchema = z.object({
+  type: ArgumentTypeSchema,
+  default: z.unknown().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  enum: z.array(z.unknown()).optional(),
+});
+
+export const ManifestEnvFieldSchema = z.object({
+  required: z.boolean().optional(),
+  description: z.string().optional(),
+});
+
+export const NodeManifestSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  consumes: z.array(z.string()),
+  emits: z.array(z.string()),
+  arguments: z.record(z.string(), ManifestArgumentSchema).optional(),
+  additional_arguments: z.boolean().optional(),
+  env: z.record(z.string(), ManifestEnvFieldSchema).optional(),
+});
+
+// ---- acpfx Flag Protocol Types ----
+
+export type {
+  SetupCheckResponse,
+  SetupProgress,
+  UnsupportedFlagResponse,
+} from "./acpfx-flags.js";
+
+export {
+  SetupCheckResponseSchema,
+  SetupProgressSchema,
+  UnsupportedFlagResponseSchema,
+} from "./acpfx-flags.js";
+
+// ---- Flag Handling ----
+
 /**
- * If `--manifest` is in process.argv, read the co-located manifest.json,
- * print it to stdout, and exit(0).
+ * Handle all `--acpfx-*` convention flags.
  *
- * Resolution order:
- * 1. Explicit `manifestPath` if provided
- * 2. `<script-base>.manifest.json` (bundled: dist/nodes/foo.js -> foo.manifest.json)
- * 3. `manifest.json` in the script's directory
+ * Must be called at the top of every node's entry point (before any async work).
+ * Also supports legacy `--manifest` for backward compatibility.
+ */
+export function handleAcpfxFlags(manifestPath?: string): void {
+  const acpfxFlag = process.argv.find((a) => a.startsWith("--acpfx-"));
+  const legacyManifest = process.argv.includes("--manifest");
+
+  if (!acpfxFlag && !legacyManifest) return;
+
+  const flag = acpfxFlag ?? "--acpfx-manifest";
+
+  switch (flag) {
+    case "--acpfx-manifest":
+      printManifest(manifestPath);
+      break;
+
+    case "--acpfx-setup-check":
+      process.stdout.write(JSON.stringify({ needed: false }) + "\n");
+      process.exit(0);
+      break;
+
+    default:
+      process.stdout.write(
+        JSON.stringify({ unsupported: true, flag }) + "\n"
+      );
+      process.exit(0);
+  }
+}
+
+/**
+ * @deprecated Use `handleAcpfxFlags()` instead.
  */
 export function handleManifestFlag(manifestPath?: string): void {
-  if (!process.argv.includes("--manifest")) return;
+  handleAcpfxFlags(manifestPath);
+}
 
+/**
+ * Print the co-located manifest JSON to stdout and exit.
+ */
+function printManifest(manifestPath?: string): void {
   if (!manifestPath) {
     const script = process.argv[1];
     const scriptDir = dirname(script);
@@ -42,7 +140,6 @@ export function handleManifestFlag(manifestPath?: string): void {
 
   try {
     const content = readFileSync(manifestPath, "utf8");
-    // Already JSON — just write it out
     process.stdout.write(content.trim() + "\n");
     process.exit(0);
   } catch (err) {