@runwingman/flightdeck-cli 0.2.0

package/src/flow-steps.js

@@ -0,0 +1,215 @@
+import crypto from 'node:crypto';
+
+const VALID_STEP_TYPES = ['job_dispatch', 'approval'];
+
+function normalizeArtifactsExpected(value) {
+  return Array.isArray(value)
+    ? value.map((item) => String(item || '').trim()).filter(Boolean)
+    : [];
+}
+
+function normalizeWhitelist(value) {
+  if (!Array.isArray(value)) return null;
+  const next = value.map((item) => String(item || '').trim()).filter(Boolean);
+  return next.length > 0 ? next : null;
+}
+
+function inferStepType(step) {
+  if (step?.type === 'job_dispatch' || step?.type === 'approval') return step.type;
+  if (!step) return 'job_dispatch';
+
+  const hasDispatchFields = [
+    step.job_type,
+    step.goals,
+    step.manager_guidance,
+    step.worker_guidance,
+    step.directory_override,
+  ].some((value) => String(value || '').trim() !== '');
+  if (hasDispatchFields) return 'job_dispatch';
+
+  const mode = step.approver_mode ?? step.approval_mode;
+  if (mode === 'manual' || mode === 'agent') return 'approval';
+  if (step.description || step.brief_template || step.whitelist_approvers || step.approver_whitelist) {
+    return 'approval';
+  }
+  return 'job_dispatch';
+}
+
+function normalizeWorkInstruction(step) {
+  return String(step?.instruction || step?.goals || step?.description || '').trim();
+}
+
+function normalizeApprovalDescription(step) {
+  return String(step?.description || step?.instruction || step?.goals || '').trim();
+}
+
+export function canonicalizeFlowStep(step) {
+  if (!step) return step;
+
+  const type = inferStepType(step);
+  if (type === 'approval') {
+    return {
+      step_number: step.step_number,
+      title: step.title ?? '',
+      type: 'approval',
+      description: normalizeApprovalDescription(step),
+      brief_template: String(step.brief_template || '').trim(),
+      approver_mode: (step.approver_mode ?? step.approval_mode) === 'agent' ? 'agent' : 'manual',
+      whitelist_approvers: normalizeWhitelist(step.whitelist_approvers ?? step.approver_whitelist),
+      artifacts_expected: normalizeArtifactsExpected(step.artifacts_expected),
+    };
+  }
+
+  return {
+    step_number: step.step_number,
+    title: step.title ?? '',
+    type: 'job_dispatch',
+    instruction: normalizeWorkInstruction(step),
+    artifacts_expected: normalizeArtifactsExpected(step.artifacts_expected),
+  };
+}
+
+export function canonicalizeFlowSteps(steps) {
+  return Array.isArray(steps) ? steps.map((step) => canonicalizeFlowStep(step)) : [];
+}
+
+/**
+ * Validates an array of flow step objects.
+ * Each step must have a step_number (positive integer) and type ('job_dispatch' or 'approval').
+ */
+export function validateFlowSteps(steps) {
+  const errors = [];
+  if (!Array.isArray(steps)) {
+    return { valid: false, errors: ['steps must be an array'] };
+  }
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const label = `step[${i}]`;
+    if (!Number.isFinite(step.step_number) || step.step_number < 1) {
+      errors.push(`${label}: step_number must be a positive integer`);
+    }
+    if (!step.type) {
+      errors.push(`${label}: type is required (job_dispatch or approval)`);
+    } else if (!VALID_STEP_TYPES.includes(step.type)) {
+      errors.push(`${label}: unknown type "${step.type}" (must be job_dispatch or approval)`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Builds an approval record payload from a flow's approval-type step.
+ */
+export function buildApprovalForStep(flow, step, runContext) {
+  const normalized = canonicalizeFlowStep(step);
+  return {
+    record_id: crypto.randomUUID(),
+    owner_npub: runContext.ownerNpub,
+    title: normalized.title ?? '',
+    description: normalized.description ?? '',
+    brief: normalized.brief_template || normalized.description || '',
+    flow_id: flow.record_id,
+    flow_run_id: runContext.flowRunId,
+    flow_step: normalized.step_number,
+    task_ids: runContext.taskIds ?? [],
+    status: 'pending',
+    approval_mode: normalized.approver_mode ?? 'manual',
+    approver_whitelist: normalized.whitelist_approvers ?? [],
+    confidence_score: null,
+    approved_by: null,
+    approved_at: null,
+    decision_note: null,
+    agent_review_by: null,
+    agent_review_note: null,
+    artifact_refs: runContext.artifactRefs ?? [],
+    revision_task_id: null,
+    scope_id: flow.scope_id ?? null,
+    scope_l1_id: flow.scope_l1_id ?? null,
+    scope_l2_id: flow.scope_l2_id ?? null,
+    scope_l3_id: flow.scope_l3_id ?? null,
+    scope_l4_id: flow.scope_l4_id ?? null,
+    scope_l5_id: flow.scope_l5_id ?? null,
+    shares: runContext.shares ?? [],
+    group_ids: runContext.groupIds ?? [],
+    record_state: 'active',
+    version: 0,
+  };
+}
+
+/**
+ * Builds a task record payload from a flow's job_dispatch-type step.
+ */
+export function buildTaskForStep(flow, step, runContext) {
+  const normalized = canonicalizeFlowStep(step);
+  return {
+    record_id: crypto.randomUUID(),
+    owner_npub: runContext.ownerNpub,
+    title: normalized.title ?? '',
+    description: normalized.instruction ?? '',
+    state: 'ready',
+    priority: 'sand',
+    flow_id: flow.record_id,
+    flow_run_id: runContext.flowRunId,
+    flow_step: normalized.step_number,
+    predecessor_task_ids: runContext.predecessorTaskIds ?? [],
+    scope_id: flow.scope_id ?? null,
+    scope_l1_id: flow.scope_l1_id ?? null,
+    scope_l2_id: flow.scope_l2_id ?? null,
+    scope_l3_id: flow.scope_l3_id ?? null,
+    scope_l4_id: flow.scope_l4_id ?? null,
+    scope_l5_id: flow.scope_l5_id ?? null,
+    shares: runContext.shares ?? [],
+    group_ids: runContext.groupIds ?? [],
+    record_state: 'active',
+    version: 0,
+  };
+}
+
+/**
+ * Starts a flow run: generates a flow_run_id and returns the first step.
+ */
+export function startFlowRun(flow) {
+  const steps = flow.steps ?? [];
+  if (steps.length === 0) {
+    throw new Error(`Flow "${flow.title ?? flow.record_id}" has no steps`);
+  }
+  const sorted = canonicalizeFlowSteps(steps).sort((a, b) => a.step_number - b.step_number);
+  return {
+    flow_id: flow.record_id,
+    flow_run_id: crypto.randomUUID(),
+    current_step: sorted[0].step_number,
+    first_step: sorted[0],
+    total_steps: steps.length,
+  };
+}
+
+/**
+ * Executes a specific flow step by dispatching to the correct builder.
+ * Returns { type, task, approval } where one of task/approval is populated.
+ */
+export function executeFlowStep(flow, stepNumber, runContext) {
+  const steps = flow.steps ?? [];
+  const rawStep = steps.find((s) => s.step_number === stepNumber);
+  const step = canonicalizeFlowStep(rawStep);
+  if (!step) {
+    throw new Error(`Step ${stepNumber} not found in flow "${flow.title ?? flow.record_id}"`);
+  }
+
+  if (step.type === 'job_dispatch') {
+    return {
+      type: 'job_dispatch',
+      task: buildTaskForStep(flow, step, runContext),
+      approval: null,
+    };
+  }
+
+  if (step.type === 'approval') {
+    return {
+      type: 'approval',
+      task: null,
+      approval: buildApprovalForStep(flow, step, runContext),
+    };
+  }
+
+  throw new Error(`Unknown step type "${step.type}" at step ${stepNumber}`);
+}

package/src/nostr.js

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { finalizeEvent, generateSecretKey, getPublicKey, nip19, nip44 } from 'nostr-tools';
+
+function hexToBytes(hex) {
+  const normalized = String(hex || '').trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(normalized)) throw new Error('Invalid secret hex.');
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < normalized.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(normalized.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+function loadNsecFromBitwarden() {
+  const sessionPath = path.join(os.homedir(), '.bw_session');
+  if (!fs.existsSync(sessionPath)) return null;
+  const bwSession = fs.readFileSync(sessionPath, 'utf8').trim();
+  return childProcess.execFileSync('bw', ['get', 'password', 'wm21-nostr'], {
+    env: { ...process.env, BW_SESSION: bwSession },
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function loadSecretFromWingmen() {
+  const wingmanUrl = String(process.env.WINGMAN_URL || '').trim();
+  const sessionId = String(process.env.SESSION_ID || '').trim();
+  if (!wingmanUrl || !sessionId) return null;
+
+  try {
+    const url = new URL('/api/bot-keys/export-nsec', wingmanUrl).toString();
+    const payload = JSON.stringify({ sessionId });
+    const script = `
+const url = ${JSON.stringify(url)};
+const payload = ${JSON.stringify(payload)};
+const response = await fetch(url, {
+  method: 'POST',
+  headers: {
+    'content-type': 'application/json',
+    'connection': 'close',
+  },
+  body: payload,
+});
+if (!response.ok) {
+  const text = await response.text().catch(() => '');
+  throw new Error(text || response.statusText || String(response.status));
+}
+const data = await response.json();
+if (!data?.nsec || typeof data.nsec !== 'string') {
+  throw new Error('Missing nsec in response');
+}
+process.stdout.write(data.nsec.trim());
+process.exit(0);
+`;
+    const output = childProcess.execFileSync(process.execPath, ['--input-type=module', '-e', script], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+
+export function getConfiguredNsec() {
+  return process.env.FLIGHTDECK_CLI_NSEC
+    || process.env.WINGMAN_YOKE_NSEC
+    || process.env.AGENT_NSEC
+    || loadSecretFromWingmen()
+    || process.env.WINGMAN_AUTOPILOT_NSEC
+    || process.env.NOSTR_NSEC
+    || loadNsecFromBitwarden();
+}
+
+export function decodeNsec(nsec) {
+  const decoded = nip19.decode(String(nsec).trim());
+  if (decoded.type !== 'nsec') throw new Error('Invalid nsec.');
+  return decoded.data;
+}
+
+export function decodeSecret(secret) {
+  const value = String(secret || '').trim();
+  if (!value) throw new Error('Missing secret.');
+  if (/^[0-9a-fA-F]{64}$/.test(value)) return hexToBytes(value);
+  return decodeNsec(value);
+}
+
+export function decodeNpub(npub) {
+  const decoded = nip19.decode(String(npub).trim());
+  if (decoded.type !== 'npub') throw new Error(`Invalid npub: ${npub}`);
+  return decoded.data;
+}
+
+export function encodeNsec(secret) {
+  return nip19.nsecEncode(secret);
+}
+
+export function createGroupIdentity(secret = generateSecretKey()) {
+  const pubkey = getPublicKey(secret);
+  return {
+    secret,
+    pubkey,
+    npub: nip19.npubEncode(pubkey),
+    nsec: encodeNsec(secret),
+  };
+}
+
+export function buildWrappedMemberKeys(groupIdentity, memberNpubs, wrappedByNpub, wrappedBySecret) {
+  const uniqueMembers = [...new Set((memberNpubs || []).map((value) => String(value || '').trim()).filter(Boolean))];
+  return uniqueMembers.map((member_npub) => ({
+    member_npub,
+    wrapped_group_nsec: encryptForNpub(wrappedBySecret, member_npub, groupIdentity.nsec),
+    wrapped_by_npub: wrappedByNpub,
+  }));
+}
+
+export function getSession(secret = decodeSecret(getConfiguredNsec())) {
+  const pubkey = getPublicKey(secret);
+  return {
+    secret,
+    pubkey,
+    npub: nip19.npubEncode(pubkey),
+  };
+}
+
+function sha256Hex(input) {
+  return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+
+export function createNip98AuthHeader(url, method, body, secret) {
+  const tags = [
+    ['u', url],
+    ['method', method.toUpperCase()],
+  ];
+  if (body != null && ['POST', 'PUT', 'PATCH'].includes(method.toUpperCase())) {
+    const serialized = typeof body === 'string' ? body : JSON.stringify(body);
+    tags.push(['payload', sha256Hex(serialized)]);
+  }
+  const event = finalizeEvent({
+    kind: 27235,
+    created_at: Math.floor(Date.now() / 1000),
+    tags,
+    content: '',
+  }, secret);
+  return `Nostr ${Buffer.from(JSON.stringify(event)).toString('base64')}`;
+}
+
+export function encryptForNpub(secret, recipientNpub, plaintext) {
+  const conversationKey = nip44.v2.utils.getConversationKey(secret, decodeNpub(recipientNpub));
+  return nip44.v2.encrypt(plaintext, conversationKey);
+}
+
+export function decryptFromNpub(secret, senderNpub, ciphertext) {
+  const conversationKey = nip44.v2.utils.getConversationKey(secret, decodeNpub(senderNpub));
+  return nip44.v2.decrypt(ciphertext, conversationKey);
+}

package/src/render.js

@@ -0,0 +1,34 @@
+const STORAGE_LINK_RE = /storage:\/\/([a-f0-9-]+)/gi;
+
+export function extractStorageObjectIds(text) {
+  const ids = new Set();
+  for (const match of String(text || '').matchAll(STORAGE_LINK_RE)) {
+    if (match[1]) ids.add(match[1]);
+  }
+  return [...ids];
+}
+
+export async function resolveStorageLinks(client, text) {
+  const objectIds = extractStorageObjectIds(text);
+  const resolved = [];
+  for (const objectId of objectIds) {
+    try {
+      const storageObject = await client.getStorageObject(objectId);
+      resolved.push({
+        object_id: objectId,
+        file_name: storageObject.file_name || null,
+        content_type: storageObject.content_type || null,
+        size_bytes: storageObject.size_bytes ?? null,
+        content_url: storageObject.content_url || client.getStorageContentUrl(objectId),
+        download_url: storageObject.download_url || null,
+        completed_at: storageObject.completed_at || null,
+      });
+    } catch (error) {
+      resolved.push({
+        object_id: objectId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return resolved;
+}

package/src/sqlite-runtime.js

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export function assertNodeRuntime() {
+  if (typeof Bun !== 'undefined') {
+    throw new Error(
+      'FlightDeck CLI currently supports Node.js only. Run it with `node src/cli.js` in a local clone, or use the installed `flightdeck-cli` binary.',
+    );
+  }
+}
+
+export function loadBetterSqlite3() {
+  assertNodeRuntime();
+  const mod = require('better-sqlite3');
+  return mod?.default ?? mod;
+}

package/src/storage.js

@@ -0,0 +1,191 @@
+import { basename, extname } from 'node:path';
+import { createHash, webcrypto } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const MIME_BY_EXT = new Map([
+  ['.png', 'image/png'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.gif', 'image/gif'],
+  ['.webp', 'image/webp'],
+  ['.svg', 'image/svg+xml'],
+  ['.mp3', 'audio/mpeg'],
+  ['.wav', 'audio/wav'],
+  ['.m4a', 'audio/mp4'],
+  ['.aac', 'audio/aac'],
+  ['.ogg', 'audio/ogg'],
+  ['.oga', 'audio/ogg'],
+  ['.opus', 'audio/ogg'],
+  ['.webm', 'audio/webm'],
+  ['.aif', 'audio/aiff'],
+  ['.aiff', 'audio/aiff'],
+  ['.txt', 'text/plain'],
+  ['.md', 'text/markdown'],
+  ['.json', 'application/json'],
+  ['.pdf', 'application/pdf'],
+]);
+
+const BROWSER_FRIENDLY_AUDIO = new Set([
+  'audio/webm',
+  'audio/webm;codecs=opus',
+  'audio/ogg',
+  'audio/mp4',
+  'audio/mpeg',
+  'audio/wav',
+]);
+
+function bytesToBase64(bytes) {
+  return Buffer.from(bytes).toString('base64');
+}
+
+export function detectMimeType(filePath, fallback = 'application/octet-stream') {
+  const ext = extname(String(filePath || '')).toLowerCase();
+  return MIME_BY_EXT.get(ext) || fallback;
+}
+
+export function readFileBytes(filePath) {
+  return new Uint8Array(readFileSync(filePath));
+}
+
+export function sha256Hex(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function defaultFileName(filePath, fallbackPrefix = 'upload') {
+  const base = basename(String(filePath || '').trim());
+  if (base) return base;
+  return `${fallbackPrefix}.bin`;
+}
+
+export function createStorageMarkdown(objectId, fileName = 'image') {
+  const safeAlt = String(fileName || 'image').replace(/[\]\[]/g, '').trim() || 'image';
+  return `![${safeAlt}](storage://${objectId})`;
+}
+
+export async function uploadFileToStorage(client, filePath, {
+  ownerNpub,
+  accessGroupIds = [],
+  ownerGroupId = null,
+  contentType = null,
+  fileName = null,
+} = {}) {
+  const bytes = readFileBytes(filePath);
+  const nextFileName = fileName || defaultFileName(filePath, 'upload');
+  const nextContentType = contentType || detectMimeType(filePath);
+  const body = {
+    owner_npub: ownerNpub,
+    content_type: nextContentType,
+    size_bytes: bytes.byteLength,
+    file_name: nextFileName,
+    access_group_ids: accessGroupIds,
+  };
+  const resolvedOwnerGroupId = ownerGroupId || accessGroupIds[0] || null;
+  if (resolvedOwnerGroupId) body.owner_group_id = resolvedOwnerGroupId;
+  const prepared = await client.prepareStorageObject(body);
+  await client.uploadPreparedStorageObject(prepared, bytes, nextContentType);
+  await client.completeStorageObject(prepared.object_id, {
+    size_bytes: bytes.byteLength,
+    sha256_hex: sha256Hex(bytes),
+  });
+  return {
+    ...prepared,
+    object_id: prepared.object_id,
+    size_bytes: bytes.byteLength,
+    content_type: nextContentType,
+    file_name: nextFileName,
+    sha256_hex: sha256Hex(bytes),
+  };
+}
+
+export async function encryptAudioBytes(bytes) {
+  const key = await webcrypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+  const iv = webcrypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await webcrypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, bytes);
+  const rawKey = new Uint8Array(await webcrypto.subtle.exportKey('raw', key));
+  return {
+    encryptedBytes: new Uint8Array(ciphertext),
+    mediaEncryption: {
+      scheme: 'aes-gcm',
+      key_b64: bytesToBase64(rawKey),
+      iv_b64: bytesToBase64(iv),
+    },
+  };
+}
+
+export async function uploadEncryptedAudioToStorage(client, filePath, {
+  ownerNpub,
+  accessGroupIds = [],
+  ownerGroupId = null,
+  contentType = null,
+  fileName = null,
+} = {}) {
+  const normalized = normalizeAudioInput(filePath, contentType);
+  try {
+    const plainBytes = readFileBytes(normalized.filePath);
+    const encrypted = await encryptAudioBytes(plainBytes);
+    const nextFileName = fileName || normalized.fileName || defaultFileName(normalized.filePath, 'voice-note');
+    const nextContentType = normalized.contentType || detectMimeType(normalized.filePath, 'audio/webm');
+    const body = {
+      owner_npub: ownerNpub,
+      content_type: nextContentType,
+      size_bytes: encrypted.encryptedBytes.byteLength,
+      file_name: nextFileName,
+      access_group_ids: accessGroupIds,
+    };
+    const resolvedOwnerGroupId = ownerGroupId || accessGroupIds[0] || null;
+    if (resolvedOwnerGroupId) body.owner_group_id = resolvedOwnerGroupId;
+    const prepared = await client.prepareStorageObject(body);
+    await client.uploadPreparedStorageObject(prepared, encrypted.encryptedBytes, nextContentType);
+    await client.completeStorageObject(prepared.object_id, {
+      size_bytes: encrypted.encryptedBytes.byteLength,
+      sha256_hex: sha256Hex(encrypted.encryptedBytes),
+    });
+    return {
+      ...prepared,
+      object_id: prepared.object_id,
+      size_bytes: encrypted.encryptedBytes.byteLength,
+      content_type: nextContentType,
+      file_name: nextFileName,
+      sha256_hex: sha256Hex(encrypted.encryptedBytes),
+      media_encryption: encrypted.mediaEncryption,
+    };
+  } finally {
+    normalized.cleanup();
+  }
+}
+
+function normalizeAudioInput(filePath, providedContentType = null) {
+  const nextContentType = providedContentType || detectMimeType(filePath, 'audio/webm');
+  const nextFileName = defaultFileName(filePath, 'voice-note');
+  if (BROWSER_FRIENDLY_AUDIO.has(nextContentType)) {
+    return {
+      filePath,
+      contentType: nextContentType,
+      fileName: nextFileName,
+      cleanup() {},
+    };
+  }
+  if (nextContentType === 'audio/aiff') {
+    const tmpDir = mkdtempSync(`${tmpdir()}/wm-ap-audio-`);
+    const wavPath = `${tmpDir}/${basename(filePath, extname(filePath))}.wav`;
+    execFileSync('afconvert', ['-f', 'WAVE', '-d', 'LEI16@44100', filePath, wavPath], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    return {
+      filePath: wavPath,
+      contentType: 'audio/wav',
+      fileName: `${basename(filePath, extname(filePath))}.wav`,
+      cleanup() {
+        rmSync(tmpDir, { recursive: true, force: true });
+      },
+    };
+  }
+  return {
+    filePath,
+    contentType: nextContentType,
+    fileName: nextFileName,
+    cleanup() {},
+  };
+}