dsh-skill-importer 0.2.0 → 0.2.1

package/src/types.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared wire types between the host half (HTTP routes) and the client half
+ * (fetch calls). Pure types — no runtime code, no node imports — so the
+ * browser bundle can reference them safely.
+ */
+
+/** Where the imported skill file should land. */
+export type ImportTarget = 'user' | 'project-agents'
+
+/** One installed skill row served by `/skill-importer/list`. */
+export interface SkillListEntry {
+  /** Kebab-case skill name (frontmatter `name`). */
+  readonly name: string
+  /** One-line routing description (frontmatter `description`). */
+  readonly description: string
+  /** Optional routing guidance (frontmatter `whenToUse`). */
+  readonly whenToUse?: string
+  /** False marks a user-only skill (`disable-model-invocation`). */
+  readonly modelInvocable: boolean
+  /** False marks a model-only skill (`user-invocable: false`). */
+  readonly userInvocable: boolean
+  /** Skill root (`'project-agents'` or `'user'`). */
+  readonly source: ImportTarget
+}
+
+/** File-import request body. */
+export interface ImportRequest {
+  readonly name: string
+  readonly target: ImportTarget
+  /** Full Markdown skill file text (frontmatter included). */
+  readonly content: string
+  /** Canonical workspace path for project targets (host-validated against the registry). */
+  readonly workspacePath?: string
+}
+
+/** Delete-request body. */
+export interface DeleteRequest {
+  readonly name: string
+  /** Which root the copy lives in (`'project-agents'` or `'user'`). */
+  readonly source: ImportTarget
+  /** Canonical workspace path for project sources (host-validated). */
+  readonly workspacePath?: string
+}
+
+/** URL-import request body. */
+export interface ImportUrlRequest {
+  readonly name: string
+  readonly target: ImportTarget
+  /** Source URL the host fetches (`.md` preferred; HTML is roughly extracted). */
+  readonly url: string
+  /** Canonical workspace path for project targets (host-validated against the registry). */
+  readonly workspacePath?: string
+}
+
+/** Read-only preflight request for one local skills directory. */
+export interface BatchScanRequest {
+  readonly sourcePath: string
+  readonly target: ImportTarget
+  readonly workspacePath?: string
+}
+
+/** One source entry reported by batch preflight. */
+export interface BatchScanEntry {
+  /** Stable row id within this one scan. */
+  readonly id: string
+  /** Frontmatter name when readable, otherwise a best-effort source label. */
+  readonly name: string
+  readonly description?: string
+  /** Path relative to the selected source directory. */
+  readonly relativePath: string
+  /** Error rows can never be selected for commit. */
+  readonly status: 'ready' | 'error'
+  readonly error?: string
+  readonly warnings?: readonly string[]
+  /** The selected destination already contains this skill name. */
+  readonly conflict: boolean
+}
+
+/** Successful batch scan; the id is single-use and expires after ten minutes. */
+export interface BatchScanResponse {
+  readonly ok: true
+  readonly scanId: string
+  readonly sourcePath: string
+  readonly entries: readonly BatchScanEntry[]
+}
+
+/** Commit a preflight, explicitly naming every destination conflict to replace. */
+export interface BatchCommitRequest {
+  readonly scanId: string
+  readonly replace: readonly string[]
+}
+
+/** Final outcome of one preflight row. */
+export interface BatchCommitEntry {
+  readonly name: string
+  readonly status: 'imported' | 'replaced' | 'skipped' | 'error'
+  readonly message?: string
+}
+
+/** One-time batch commit result. */
+export interface BatchCommitResponse {
+  readonly ok: true
+  readonly results: readonly BatchCommitEntry[]
+}
+
+/** `/skill-importer/list` response. */
+export interface SkillListResponse {
+  readonly ok: true
+  readonly skills: readonly SkillListEntry[]
+}
+
+/** Success response of an import. */
+export interface ImportResponse {
+  readonly ok: true
+  /** Absolute path of the written SKILL.md. */
+  readonly path: string
+}
+
+/** Error response of any route. */
+export interface ErrorResponse {
+  readonly ok: false
+  readonly error: string
+}

package/tests/batch-import.test.mjs

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict'
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { parseSkillFile, validateSkillFile } from '../src/frontmatter.ts'
+import { assertSafeImportUrl, commitBatch, isPrivateAddress, originAllowed, scanBatch } from '../src/server.ts'
+
+const sandbox = mkdtempSync(join(tmpdir(), 'dsh-batch-test-'))
+process.env.DSH_HOME = join(sandbox, 'home')
+
+const skill = (name, description = `Description for ${name}`) => `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n`
+
+const crlfSkill = skill('windows-crlf').replace(/\n/g, '\r\n')
+assert.equal(parseSkillFile(crlfSkill).frontmatter.name, 'windows-crlf')
+assert.equal(validateSkillFile(crlfSkill), undefined)
+assert.equal(parseSkillFile(skill('legacy-cr').replace(/\n/g, '\r')).frontmatter.name, 'legacy-cr')
+
+try {
+  const source = join(sandbox, '.claude', 'skills')
+  mkdirSync(source, { recursive: true })
+
+  // A complete directory skill proves resources survive the migration.
+  mkdirSync(join(source, 'alpha', 'scripts'), { recursive: true })
+  writeFileSync(join(source, 'alpha', 'SKILL.md'), skill('alpha'))
+  writeFileSync(join(source, 'alpha', 'scripts', 'run.sh'), 'echo alpha\n')
+
+  // Windows CRLF skills must pass the same batch preflight and normalize to LF.
+  mkdirSync(join(source, 'windows-crlf'), { recursive: true })
+  writeFileSync(join(source, 'windows-crlf', 'SKILL.md'), crlfSkill)
+
+  // Invalid metadata must be reported but never written.
+  mkdirSync(join(source, 'invalid'), { recursive: true })
+  writeFileSync(join(source, 'invalid', 'SKILL.md'), '---\nname: invalid\n---\n')
+
+  // Ambiguous names inside one batch refuse every copy.
+  for (const folder of ['dup-a', 'dup-b']) {
+    mkdirSync(join(source, folder), { recursive: true })
+    writeFileSync(join(source, folder, 'SKILL.md'), skill('duplicate'))
+  }
+
+  // Existing destination content is only replaced after explicit confirmation.
+  const existing = join(process.env.DSH_HOME, 'skills', 'alpha')
+  mkdirSync(existing, { recursive: true })
+  writeFileSync(join(existing, 'SKILL.md'), skill('alpha', 'old'))
+
+  const scan = scanBatch({ sourcePath: source, target: 'user' })
+  assert.equal(scan.entries.find(row => row.name === 'alpha')?.conflict, true)
+  assert.equal(scan.entries.find(row => row.name === 'windows-crlf')?.status, 'ready')
+  assert.equal(scan.entries.find(row => row.name === 'invalid')?.status, 'error')
+  assert.equal(scan.entries.filter(row => row.name === 'duplicate' && row.status === 'error').length, 2)
+
+  const results = commitBatch(scan, new Set(['alpha']))
+  assert.equal(results.find(row => row.name === 'alpha')?.status, 'replaced')
+  assert.equal(results.find(row => row.name === 'windows-crlf')?.status, 'imported')
+  assert.equal(results.filter(row => row.name === 'duplicate' && row.status === 'error').length, 2)
+  assert.equal(existsSync(join(process.env.DSH_HOME, 'skills', 'alpha', 'scripts', 'run.sh')), true)
+  assert.match(readFileSync(join(process.env.DSH_HOME, 'skills', 'alpha', 'SKILL.md'), 'utf8'), /Description for alpha/)
+  assert.doesNotMatch(readFileSync(join(process.env.DSH_HOME, 'skills', 'windows-crlf', 'SKILL.md'), 'utf8'), /\r/)
+  assert.equal(existsSync(join(process.env.DSH_HOME, 'skills', 'invalid')), false)
+  assert.equal(existsSync(join(process.env.DSH_HOME, 'skills', 'duplicate')), false)
+
+  // A changed source invalidates the preflight and leaves no partial destination.
+  const changedSource = join(sandbox, '.codex', 'skills')
+  mkdirSync(join(changedSource, 'beta'), { recursive: true })
+  writeFileSync(join(changedSource, 'beta', 'SKILL.md'), skill('beta'))
+  const changedScan = scanBatch({ sourcePath: changedSource, target: 'user' })
+  writeFileSync(join(changedSource, 'beta', 'SKILL.md'), skill('beta', 'changed after scan'))
+  const changedResults = commitBatch(changedScan, new Set())
+  assert.equal(changedResults[0]?.status, 'error')
+  assert.match(changedResults[0]?.message ?? '', /发生变化/)
+  assert.equal(existsSync(join(process.env.DSH_HOME, 'skills', 'beta')), false)
+
+  const empty = join(sandbox, '.agents', 'skills')
+  mkdirSync(empty, { recursive: true })
+  assert.throws(() => scanBatch({ sourcePath: empty, target: 'user' }), /没有找到/)
+
+  const arbitrary = join(sandbox, 'arbitrary')
+  mkdirSync(arbitrary)
+  assert.throws(() => scanBatch({ sourcePath: arbitrary, target: 'user' }), /仅支持/)
+
+  assert.equal(originAllowed({ headers: {} }), false)
+  assert.equal(originAllowed({ headers: { origin: 'https://evil.example' } }), false)
+  assert.equal(originAllowed({ headers: { origin: 'http://127.0.0.1:2026' } }), true)
+  assert.equal(isPrivateAddress('127.0.0.1'), true)
+  assert.equal(isPrivateAddress('169.254.169.254'), true)
+  assert.equal(isPrivateAddress('10.0.0.1'), true)
+  assert.equal(isPrivateAddress('::1'), true)
+  assert.equal(isPrivateAddress('8.8.8.8'), false)
+  await assert.rejects(assertSafeImportUrl('http://example.com/skill.md'), /仅支持 HTTPS/)
+  await assert.rejects(assertSafeImportUrl('https://localhost/skill.md'), /私有网络/)
+  await assert.rejects(assertSafeImportUrl('https://[::1]/skill.md'), /私有网络|保留地址/)
+  await assert.rejects(
+    assertSafeImportUrl('https://internal.example/skill.md', async () => [{ address: '10.0.0.2' }]),
+    /私有网络/,
+  )
+  const publicUrl = await assertSafeImportUrl(
+    'https://skills.example/skill.md',
+    async () => [{ address: '93.184.216.34' }],
+  )
+  assert.equal(publicUrl.hostname, 'skills.example')
+  console.log('batch import test: OK')
+} finally {
+  rmSync(sandbox, { recursive: true, force: true })
+}