@oneworks/cli 0.1.0-alpha.0

package/src/commands/memory/entries.ts

@@ -0,0 +1,131 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { resolveContext } from './context'
+import { META_FILE_NAME, ensureRelativeMemoryPath, fromStorageSegment, normalizeScope, trimNonEmpty } from './shared'
+import type { MemoryCommandOptions, MemoryScope } from './shared'
+
+interface MemoryEntry {
+  channel?: string
+  id?: string
+  memoryPath: string
+  scope: MemoryScope
+  size: number
+}
+
+const decodeEntryParts = (scope: MemoryScope, parts: string[]) => {
+  if (scope === 'global') {
+    return { fileParts: parts, id: undefined, channel: undefined }
+  }
+  if (scope === 'session') {
+    return {
+      fileParts: parts.slice(1),
+      id: parts[0] == null ? undefined : fromStorageSegment(parts[0]),
+      channel: undefined
+    }
+  }
+  return {
+    fileParts: parts.slice(2),
+    id: parts[1] == null ? undefined : fromStorageSegment(parts[1]),
+    channel: parts[0] == null ? undefined : fromStorageSegment(parts[0])
+  }
+}
+
+const maybeAddEntry = async (
+  entries: MemoryEntry[],
+  filePath: string,
+  fileName: string,
+  options: {
+    channel?: string
+    id?: string
+    memoryPathFilter?: string
+    parts: string[]
+    scope: MemoryScope
+  }
+) => {
+  const decoded = decodeEntryParts(options.scope, options.parts)
+  if (options.channel != null && decoded.channel !== options.channel) return
+  if (options.id != null && decoded.id !== options.id) return
+  const memoryPath = decoded.fileParts.length === 0 ? fileName : [...decoded.fileParts, fileName].join('/')
+  if (options.memoryPathFilter != null && memoryPath !== options.memoryPathFilter) return
+
+  const stat = await fs.stat(filePath)
+  entries.push({
+    channel: decoded.channel,
+    id: decoded.id,
+    memoryPath,
+    scope: options.scope,
+    size: stat.size
+  })
+}
+
+const collectEntriesUnder = async (
+  root: string,
+  scope: MemoryScope,
+  channel: string | undefined,
+  id: string | undefined,
+  requestedPath: string | undefined
+) => {
+  const entries: MemoryEntry[] = []
+  const memoryPathFilter = requestedPath == null ? undefined : ensureRelativeMemoryPath(requestedPath)
+
+  const walk = async (dir: string, parts: string[]) => {
+    let items: import('node:fs').Dirent[]
+    try {
+      items = await fs.readdir(dir, { withFileTypes: true })
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+      throw error
+    }
+
+    for (const item of items) {
+      if (item.name === META_FILE_NAME) continue
+      const itemPath = path.resolve(dir, item.name)
+      if (item.isDirectory()) {
+        await walk(itemPath, [...parts, item.name])
+      } else if (item.isFile()) {
+        await maybeAddEntry(entries, itemPath, item.name, { channel, id, memoryPathFilter, parts, scope })
+      }
+    }
+  }
+
+  await walk(root, [])
+  return entries
+}
+
+const scopeRootName = (scope: MemoryScope) => {
+  if (scope === 'global') return 'global'
+  if (scope === 'channel') return 'channels'
+  if (scope === 'session') return 'sessions'
+  return 'users'
+}
+
+export const listMemoryEntries = async (options: MemoryCommandOptions) => {
+  const context = resolveContext(options)
+  const scope = normalizeScope(options.scope)
+  const entries = await collectEntriesUnder(
+    path.resolve(context.root, scopeRootName(scope)),
+    scope,
+    trimNonEmpty(options.channel),
+    trimNonEmpty(options.filter),
+    options.path
+  )
+  return entries.sort((left, right) =>
+    `${left.scope}:${left.channel ?? ''}:${left.id ?? ''}:${left.memoryPath}`.localeCompare(
+      `${right.scope}:${right.channel ?? ''}:${right.id ?? ''}:${right.memoryPath}`
+    )
+  )
+}
+
+export const formatEntries = (entries: MemoryEntry[]) => {
+  if (entries.length === 0) return 'No memories found.'
+  return entries.map(entry =>
+    [
+      entry.scope,
+      entry.channel,
+      entry.id,
+      entry.memoryPath,
+      `${entry.size}B`
+    ].filter(Boolean).join('\t')
+  ).join('\n')
+}

package/src/commands/memory/shared.ts

@@ -0,0 +1,89 @@
+import { Buffer } from 'node:buffer'
+import path from 'node:path'
+
+export type MemoryScope = 'global' | 'channel' | 'session' | 'user'
+export type MemoryAction = 'get' | 'list' | 'patch' | 'set'
+
+export interface MemoryCommandOptions {
+  channel?: string
+  content?: string
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  filter?: string
+  path?: string
+  scope?: string
+}
+
+export interface MemoryCommandResult {
+  output: string
+}
+
+export interface MemoryContext {
+  channelId?: string
+  channelKey?: string
+  channelRef?: string
+  channelSessionType?: string
+  channelType?: string
+  root: string
+  senderId?: string
+  sessionId?: string
+}
+
+export interface MemoryTarget {
+  dir: string
+  displayId?: string
+  filePath: string
+  memoryPath: string
+  scope: MemoryScope
+}
+
+export const DEFAULT_MEMORY_PATH = 'README.md'
+export const META_FILE_NAME = '.oneworks-mem.json'
+
+const MEMORY_SCOPES = new Set<MemoryScope>(['global', 'channel', 'session', 'user'])
+
+export const trimNonEmpty = (value: unknown) => {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed === '' ? undefined : trimmed
+}
+
+export const normalizeScope = (value: string | undefined): MemoryScope => {
+  const scope = trimNonEmpty(value) ?? 'channel'
+  if (MEMORY_SCOPES.has(scope as MemoryScope)) return scope as MemoryScope
+  throw new Error(`Unsupported memory scope: ${scope}. Supported: global, channel, session, user.`)
+}
+
+export const ensureRelativeMemoryPath = (value: string | undefined) => {
+  const raw = trimNonEmpty(value) ?? DEFAULT_MEMORY_PATH
+  if (raw.includes('\0')) throw new Error('Memory path cannot contain NUL bytes.')
+  if (path.isAbsolute(raw)) throw new Error('Memory path must be relative.')
+
+  const normalized = path.posix.normalize(raw.replaceAll('\\', '/')).replace(/^\.\//u, '')
+  if (
+    normalized === '' ||
+    normalized === '.' ||
+    normalized === '..' ||
+    normalized.startsWith('../')
+  ) {
+    throw new Error('Memory path must stay inside the selected memory id.')
+  }
+  return normalized
+}
+
+export const toStorageSegment = (value: string) => Buffer.from(value, 'utf8').toString('base64url')
+
+export const fromStorageSegment = (value: string) => {
+  try {
+    return Buffer.from(value, 'base64url').toString('utf8')
+  } catch {
+    return value
+  }
+}
+
+export const formatTargetLabel = (target: MemoryTarget) =>
+  [
+    target.scope,
+    target.displayId,
+    target.memoryPath
+  ].filter(Boolean).join(':')

package/src/commands/memory/store.ts

@@ -0,0 +1,69 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { formatEntries, listMemoryEntries } from './entries'
+import { META_FILE_NAME, formatTargetLabel } from './shared'
+import type { MemoryCommandOptions, MemoryContext, MemoryTarget } from './shared'
+import { resolveTarget } from './target'
+
+const writeMeta = async (target: MemoryTarget, context: MemoryContext) => {
+  await fs.mkdir(target.dir, { recursive: true })
+  await fs.writeFile(
+    path.resolve(target.dir, META_FILE_NAME),
+    `${
+      JSON.stringify(
+        {
+          channel: context.channelRef,
+          channelId: context.channelId,
+          channelKey: context.channelKey,
+          channelSessionType: context.channelSessionType,
+          channelType: context.channelType,
+          id: target.displayId,
+          scope: target.scope,
+          senderId: context.senderId,
+          sessionId: context.sessionId,
+          updatedAt: Date.now()
+        },
+        null,
+        2
+      )
+    }\n`
+  )
+}
+
+const withTrailingNewline = (value: string) => value.endsWith('\n') ? value : `${value}\n`
+
+export const readFileIfPresent = async (filePath: string) => {
+  try {
+    return await fs.readFile(filePath, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw error
+  }
+}
+
+export const readMemory = async (options: MemoryCommandOptions) => {
+  const { target } = resolveTarget(options)
+  return await readFileIfPresent(target.filePath)
+}
+
+export const listMemory = async (options: MemoryCommandOptions) => formatEntries(await listMemoryEntries(options))
+
+export const writeMemory = async (mode: 'patch' | 'set', options: MemoryCommandOptions) => {
+  const { context, target } = resolveTarget(options)
+  const content = options.content ?? ''
+  await fs.mkdir(path.dirname(target.filePath), { recursive: true })
+  await writeMeta(target, context)
+
+  if (mode === 'set') {
+    await fs.writeFile(target.filePath, withTrailingNewline(content))
+  } else {
+    const current = await readFileIfPresent(target.filePath)
+    const next = current === ''
+      ? withTrailingNewline(content)
+      : `${current}${current.endsWith('\n') ? '' : '\n'}${withTrailingNewline(content)}`
+    await fs.writeFile(target.filePath, next)
+  }
+
+  return `Memory ${mode === 'set' ? 'written' : 'patched'}: ${formatTargetLabel(target)}`
+}

package/src/commands/memory/target.ts

@@ -0,0 +1,54 @@
+import path from 'node:path'
+
+import { resolveContext } from './context'
+import type { MemoryCommandOptions, MemoryContext, MemoryScope, MemoryTarget } from './shared'
+import { ensureRelativeMemoryPath, normalizeScope, toStorageSegment, trimNonEmpty } from './shared'
+
+const requireValue = (value: string | undefined, message: string) => {
+  if (value != null && value !== '') return value
+  throw new Error(message)
+}
+
+const resolveTargetId = (scope: MemoryScope, context: MemoryContext, filter: string | undefined) => {
+  const explicitId = trimNonEmpty(filter)
+  if (scope === 'global') return undefined
+  if (scope === 'channel') {
+    return requireValue(explicitId ?? context.channelId, 'Missing channel memory id. Pass -f/--filter.')
+  }
+  if (scope === 'session') {
+    return requireValue(explicitId ?? context.sessionId, 'Missing session memory id. Pass -f/--filter.')
+  }
+  return requireValue(explicitId ?? context.senderId, 'Missing user memory id. Pass -f/--filter.')
+}
+
+const resolveTargetDir = (scope: MemoryScope, context: MemoryContext, displayId?: string) => {
+  if (scope === 'global') return path.resolve(context.root, 'global')
+  if (scope === 'session') {
+    return path.resolve(context.root, 'sessions', toStorageSegment(requireValue(displayId, 'Missing session id.')))
+  }
+
+  const channelRef = requireValue(context.channelRef, 'Missing channel. Pass -c/--channel.')
+  const rootName = scope === 'channel' ? 'channels' : 'users'
+  return path.resolve(
+    context.root,
+    rootName,
+    toStorageSegment(channelRef),
+    toStorageSegment(requireValue(displayId, `Missing ${scope} memory id.`))
+  )
+}
+
+export const resolveTarget = (options: MemoryCommandOptions) => {
+  const context = resolveContext(options)
+  const scope = normalizeScope(options.scope)
+  const displayId = resolveTargetId(scope, context, options.filter)
+  const memoryPath = ensureRelativeMemoryPath(options.path)
+  const dir = resolveTargetDir(scope, context, displayId)
+  const filePath = path.resolve(dir, ...memoryPath.split('/'))
+  const relativePath = path.relative(dir, filePath)
+
+  if (relativePath === '..' || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+    throw new Error('Memory path resolved outside the selected memory id.')
+  }
+
+  return { context, target: { dir, displayId, filePath, memoryPath, scope } satisfies MemoryTarget }
+}

package/src/commands/memory.ts

@@ -0,0 +1,97 @@
+import { Buffer } from 'node:buffer'
+import process from 'node:process'
+
+import type { Command } from 'commander'
+
+import { DEFAULT_MEMORY_PATH } from './memory/shared'
+import type { MemoryAction, MemoryCommandOptions, MemoryCommandResult } from './memory/shared'
+import { listMemory, readMemory, writeMemory } from './memory/store'
+
+export type { MemoryAction, MemoryCommandOptions, MemoryCommandResult, MemoryScope } from './memory/shared'
+
+export const runMemoryCommand = async (
+  action: MemoryAction,
+  options: MemoryCommandOptions = {}
+): Promise<MemoryCommandResult> => {
+  if (action === 'list') {
+    return { output: await listMemory(options) }
+  }
+  if (action === 'get') {
+    return { output: await readMemory(options) }
+  }
+  return { output: await writeMemory(action, options) }
+}
+
+const readStdin = async () => {
+  if (process.stdin.isTTY) return ''
+
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+const joinContent = async (parts: string[]) => {
+  const value = parts.join(' ')
+  if (value !== '') return value
+  return await readStdin()
+}
+
+const printResult = (output: string) => {
+  if (output === '') return
+  process.stdout.write(output.endsWith('\n') ? output : `${output}\n`)
+}
+
+const addCommonOptions = (command: Command, options: { defaultPath?: boolean } = {}) => {
+  const withPath = options.defaultPath === false
+    ? command.option('-p, --path <path>', 'Memory file path under the selected id')
+    : command.option('-p, --path <path>', 'Memory file path under the selected id', DEFAULT_MEMORY_PATH)
+  return withPath
+    .option('-c, --channel <channel>', 'Channel type or channel ref, for example wechat')
+    .option('-f, --filter <id>', 'Memory id to target or filter')
+    .option('-s, --scope <scope>', 'Memory scope: global, channel, session, or user', 'channel')
+}
+
+const run = async (action: MemoryAction, opts: MemoryCommandOptions) => {
+  const result = await runMemoryCommand(action, opts)
+  printResult(result.output)
+}
+
+export const registerMemorySubcommands = (command: Command) => {
+  addCommonOptions(command.command('set'))
+    .description('Overwrite a memory file')
+    .argument('[content...]', 'Content to write. Reads stdin when omitted.')
+    .action(async (content: string[], options: MemoryCommandOptions) => {
+      await run('set', { ...options, content: await joinContent(content) })
+    })
+
+  addCommonOptions(command.command('patch'))
+    .description('Append content to a memory file')
+    .argument('[content...]', 'Content to append. Reads stdin when omitted.')
+    .action(async (content: string[], options: MemoryCommandOptions) => {
+      await run('patch', { ...options, content: await joinContent(content) })
+    })
+
+  addCommonOptions(command.command('get'))
+    .description('Print a memory file')
+    .action(async (options: MemoryCommandOptions) => {
+      await run('get', options)
+    })
+
+  addCommonOptions(command.command('list'), { defaultPath: false })
+    .description('List available memory files')
+    .action(async (options: MemoryCommandOptions) => {
+      await run('list', options)
+    })
+
+  return command
+}
+
+export const registerMemoryCommand = (program: Command) => {
+  registerMemorySubcommands(
+    program
+      .command('mem')
+      .description('Read and write OneWorks memory from agent sessions')
+  )
+}

package/src/commands/plugin.ts

@@ -0,0 +1,62 @@
+import process from 'node:process'
+
+import { buildConfigJsonVariables, loadConfig, mergeConfigs } from '@oneworks/config'
+import { mergeProcessEnvWithProjectEnv } from '@oneworks/utils'
+import type { Command } from 'commander'
+
+import { resolveCliWorkspaceCwd } from '#~/workspace.js'
+import { createAdapterOption, normalizeCliAdapterOptionValue } from './@core/adapter-option'
+import { addAdapterPlugin } from './@core/plugin-install'
+
+const normalizeManagedPluginAdapter = (adapter: string) => adapter === 'claude-code' ? 'claude' : adapter
+
+export const resolvePluginCommandAdapter = async (
+  explicitAdapter: string | undefined,
+  cwd: string = process.cwd()
+) => {
+  const normalizedExplicitAdapter = explicitAdapter == null
+    ? undefined
+    : normalizeCliAdapterOptionValue(explicitAdapter)
+  if (normalizedExplicitAdapter) return normalizeManagedPluginAdapter(normalizedExplicitAdapter)
+
+  const env = mergeProcessEnvWithProjectEnv(undefined, { workspaceFolder: cwd })
+  const [projectConfig, userConfig] = await loadConfig({
+    cwd,
+    env,
+    jsonVariables: buildConfigJsonVariables(cwd, env)
+  })
+  return normalizeManagedPluginAdapter(
+    mergeConfigs(projectConfig, userConfig)?.defaultAdapter ?? 'claude'
+  )
+}
+
+export function registerPluginCommand(program: Command) {
+  const pluginCommand = program
+    .command('plugin')
+    .description('Install and manage adapter-native plugins')
+    .addOption(createAdapterOption('Plugin adapter type'))
+
+  pluginCommand
+    .command('add <source>')
+    .description('Install an adapter-native plugin from local sources, package registries, or configured marketplaces')
+    .option('--force', 'Replace the existing installed plugin if it already exists', false)
+    .option('--scope <scope>', 'Override the One Works scope used for converted assets')
+    .action(async (source: string, opts: { force?: boolean; scope?: string }, command: Command) => {
+      try {
+        const parentOptions = command.parent?.opts() as { adapter?: string } | undefined
+        const cwd = resolveCliWorkspaceCwd()
+        const env = mergeProcessEnvWithProjectEnv(undefined, { workspaceFolder: cwd })
+        const adapter = await resolvePluginCommandAdapter(parentOptions?.adapter, cwd)
+        await addAdapterPlugin(adapter, {
+          cwd,
+          env,
+          source,
+          force: opts.force,
+          scope: opts.scope
+        })
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error))
+        process.exit(1)
+      }
+    })
+}

package/src/commands/report-targets.ts

@@ -0,0 +1,149 @@
+import { constants } from 'node:fs'
+import type { Dirent } from 'node:fs'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {
+  mergeProcessEnvWithProjectEnv,
+  migrateProjectHomeSegments,
+  resolveProjectHomePath,
+  resolveProjectOoPath
+} from '@oneworks/utils'
+
+const REPORT_TARGETS = ['logs', 'caches'] as const
+const REPORT_MOCK_TARGETS = [
+  '.mock/.claude',
+  '.mock/.claude-code-router',
+  '.mock/.config',
+  '.mock/.codex',
+  '.mock/.oneworks'
+] as const
+const REPORT_MOCK_FILE_PREFIX = '.claude.json'
+
+const collectExistingTargets = async (cwd: string, env: NodeJS.ProcessEnv, targets: readonly string[]) => {
+  const availableTargets: string[] = []
+
+  for (const target of targets) {
+    try {
+      const resolvedTarget = resolveProjectOoPath(cwd, env, ...target.split('/'))
+      await fs.access(resolvedTarget, constants.F_OK)
+      availableTargets.push(resolvedTarget)
+    } catch {
+      // ignore missing targets
+    }
+  }
+
+  return availableTargets
+}
+
+const collectMockReportTargets = async (cwd: string, env: NodeJS.ProcessEnv) => {
+  const availableTargets = await collectExistingTargets(cwd, env, REPORT_MOCK_TARGETS)
+  const mockRoot = resolveProjectOoPath(cwd, env, '.mock')
+
+  try {
+    const entries = await fs.readdir(mockRoot, { withFileTypes: true })
+    const mockFiles = entries
+      .filter(entry =>
+        entry.isFile() && (
+          entry.name === REPORT_MOCK_FILE_PREFIX ||
+          entry.name.startsWith(`${REPORT_MOCK_FILE_PREFIX}.backup`)
+        )
+      )
+      .map(entry => path.resolve(mockRoot, entry.name))
+      .sort((left, right) => left.localeCompare(right))
+
+    availableTargets.push(...mockFiles)
+  } catch {
+    // ignore missing mock root
+  }
+
+  return availableTargets
+}
+
+const isPathInside = (target: string, source: string) => {
+  const relativePath = path.relative(source, target)
+  return relativePath === '' || (
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relativePath)
+  )
+}
+
+const isLoggerPayloadRefPath = (entryPath: string, logRoot: string) => (
+  path.relative(logRoot, entryPath)
+    .split(path.sep)
+    .some(part => part.endsWith('.payloads'))
+)
+
+const findLoggerPayloadRefTargets = async (params: {
+  logRoot: string
+  payloadStoreRoot: string
+}): Promise<string[]> => {
+  const targets = new Set<string>()
+
+  const visit = async (current: string) => {
+    let entries: Dirent[]
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true })
+    } catch {
+      return
+    }
+
+    await Promise.all(entries.map(async (entry) => {
+      const entryPath = path.resolve(current, entry.name)
+      if (entry.isDirectory()) {
+        await visit(entryPath)
+        return
+      }
+
+      if (!entry.isSymbolicLink() || !isLoggerPayloadRefPath(entryPath, params.logRoot)) return
+
+      try {
+        const linkTarget = await fs.readlink(entryPath)
+        const resolvedTarget = path.resolve(path.dirname(entryPath), linkTarget)
+        if (!isPathInside(resolvedTarget, params.payloadStoreRoot)) return
+        await fs.access(resolvedTarget, constants.F_OK)
+        targets.add(resolvedTarget)
+      } catch {
+        // ignore dangling symlinks
+      }
+    }))
+  }
+
+  await visit(params.logRoot)
+  return [...targets].sort((left, right) => left.localeCompare(right))
+}
+
+const collectLoggerPayloadReportTargets = async (cwd: string, env: NodeJS.ProcessEnv) => {
+  const projectHomeLogsDir = resolveProjectHomePath(cwd, env, 'logs')
+  const projectHomePayloadStoreDir = resolveProjectHomePath(cwd, env, 'caches', '.logger-payloads', 'sha256')
+  const logRoots = new Set<string>()
+
+  try {
+    await fs.access(projectHomeLogsDir, constants.F_OK)
+    logRoots.add(projectHomeLogsDir)
+  } catch {
+    // ignore missing project-home logs
+  }
+  const targets = await Promise.all([...logRoots].map(logRoot =>
+    findLoggerPayloadRefTargets({
+      logRoot,
+      payloadStoreRoot: projectHomePayloadStoreDir
+    })
+  ))
+  return [...new Set(targets.flat())].sort((left, right) => left.localeCompare(right))
+}
+
+export const collectReportTargets = async (
+  cwd: string,
+  env: NodeJS.ProcessEnv = mergeProcessEnvWithProjectEnv(undefined, { workspaceFolder: cwd })
+) => {
+  await migrateProjectHomeSegments(cwd, env, ['logs', 'caches', '.mock'])
+  const availableTargets = await collectExistingTargets(cwd, env, REPORT_TARGETS)
+  const loggerPayloadTargets = await collectLoggerPayloadReportTargets(cwd, env)
+  availableTargets.push(
+    ...loggerPayloadTargets.filter(target => !availableTargets.some(source => isPathInside(target, source)))
+  )
+  availableTargets.push(...await collectMockReportTargets(cwd, env))
+  return availableTargets
+}