w-dispatch-ai 1.0.0

package/test/unit-dispatchClaude.test.mjs

@@ -0,0 +1,144 @@
+import assert from 'assert'
+import dispatchClaude from '../src/dispatchClaude.mjs'
+import createFakeCli from './tools/fakeCliForTest.mjs'
+
+
+describe('dispatchClaude', function() {
+
+    let fake = null
+
+    before(function() {
+        fake = createFakeCli('fake-claude')
+    })
+
+    after(function() {
+        if (fake) {
+            fake.clean()
+        }
+    })
+
+    it('prompt非有效字串時回傳錯誤結果物件且不reject', async function() {
+        let r = []
+        for (let prompt of [null, undefined, '', 123, {}, []]) {
+            let t = await dispatchClaude(prompt)
+            r.push([t.ok, t.error, t.attempts])
+        }
+        let rr = [
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('固定帶-p與--dangerously-skip-permissions旗標', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.args]
+        let rr = [true, ['-p', '--dangerously-skip-permissions']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('有給model時帶--model旗標', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, model: 'sonnet' })
+        let o = JSON.parse(t.stdout)
+        let r = o.args
+        let rr = ['-p', '--dangerously-skip-permissions', '--model', 'sonnet']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('model非有效字串時整段--model旗標不出現', async function() {
+        let r = []
+        for (let model of [null, undefined, '', 123, {}]) {
+            let t = await dispatchClaude('abc', { exe: fake.exe, model })
+            let o = JSON.parse(t.stdout)
+            r.push(o.args.includes('--model'))
+        }
+        let rr = [false, false, false, false, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('skipPermissions為false時不帶--dangerously-skip-permissions旗標', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, model: 'sonnet', skipPermissions: false })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.args]
+        let rr = [true, ['-p', '--model', 'sonnet']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('skipPermissions非布林值時回退預設true', async function() {
+        let r = []
+        for (let skipPermissions of [null, undefined, 1, 'false', {}]) {
+            let t = await dispatchClaude('abc', { exe: fake.exe, skipPermissions })
+            let o = JSON.parse(t.stdout)
+            r.push(o.args.includes('--dangerously-skip-permissions'))
+        }
+        let rr = [true, true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('extraArgs接於固定旗標之後', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, model: 'sonnet', extraArgs: ['--verbose', '--fake-stderr=warn'] })
+        let o = JSON.parse(t.stdout)
+        let r = o.args
+        let rr = ['-p', '--dangerously-skip-permissions', '--model', 'sonnet', '--verbose', '--fake-stderr=warn']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('prompt以stdin傳入, 中文與多行皆完整保留', async function() {
+        let prompt = '第一行中文\n第二行 with "quote" & <sym>\n第三行'
+        let t = await dispatchClaude(prompt, { exe: fake.exe })
+        let o = JSON.parse(t.stdout)
+        let r = [o.stdin === prompt, o.args.includes(prompt)]
+        let rr = [true, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('執行檔不存在時回傳ENOENT且不重試', async function() {
+        let t = await dispatchClaude('abc', { exe: 'claude-not-exist-for-test', maxRetries: 3 })
+        let r = [t.ok, t.error.includes('ENOENT'), t.attempts]
+        let rr = [false, true, 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('離開碼非0時回傳失敗', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, extraArgs: ['--fake-exit=1'] })
+        let r = [t.ok, t.code, t.error]
+        let rr = [false, 1, 'Exit code 1']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('validate驗證失敗時回傳OUTPUT_VALIDATION_FAILED', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, validate: 'min:100000' })
+        let r = [t.ok, t.code, t.error]
+        let rr = [false, 0, 'OUTPUT_VALIDATION_FAILED']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('逾時時強制關閉子進程並回傳TIMEOUT', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, extraArgs: ['--fake-sleep=10000'], timeoutMs: 1000 })
+        let r = [t.ok, t.error.includes('TIMEOUT')]
+        let rr = [false, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('cwd等execCli設定原樣轉傳', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, cwd: process.cwd() })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.cwd === process.cwd()]
+        let rr = [true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('無key概念, 給予key與provider亦不注入OPENCODE_AUTH_CONTENT', async function() {
+        let t = await dispatchClaude('abc', { exe: fake.exe, key: 'sk-abc', provider: 'opencode' })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.env.OPENCODE_AUTH_CONTENT]
+        let rr = [true, '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchCodex.test.mjs

@@ -0,0 +1,113 @@
+import assert from 'assert'
+import dispatchCodex from '../src/dispatchCodex.mjs'
+import createFakeCli from './tools/fakeCliForTest.mjs'
+
+
+describe('dispatchCodex', function() {
+
+    let fake = null
+
+    before(function() {
+        fake = createFakeCli('fake-codex')
+    })
+
+    after(function() {
+        if (fake) {
+            fake.clean()
+        }
+    })
+
+    it('prompt非有效字串時回傳錯誤結果物件且不reject', async function() {
+        let r = []
+        for (let prompt of [null, undefined, '', 123, {}, []]) {
+            let t = await dispatchCodex(prompt)
+            r.push([t.ok, t.error, t.attempts])
+        }
+        let rr = [
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('固定帶exec與--skip-git-repo-check旗標, sandbox預設workspace-write', async function() {
+        let t = await dispatchCodex('abc', { exe: fake.exe })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.args]
+        let rr = [true, ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('有給model時帶-m旗標', async function() {
+        let t = await dispatchCodex('abc', { exe: fake.exe, model: 'gpt-5.6-luna' })
+        let o = JSON.parse(t.stdout)
+        let r = o.args
+        let rr = ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-m', 'gpt-5.6-luna']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('model非有效字串時整段-m旗標不出現', async function() {
+        let r = []
+        for (let model of [null, undefined, '', 123, {}]) {
+            let t = await dispatchCodex('abc', { exe: fake.exe, model })
+            let o = JSON.parse(t.stdout)
+            r.push(o.args.includes('-m'))
+        }
+        let rr = [false, false, false, false, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('sandbox可自訂, 非有效字串則回退workspace-write', async function() {
+        let t1 = await dispatchCodex('abc', { exe: fake.exe, sandbox: 'read-only' })
+        let t2 = await dispatchCodex('abc', { exe: fake.exe, sandbox: 123 })
+        let r = [
+            JSON.parse(t1.stdout).args[2],
+            JSON.parse(t2.stdout).args[2],
+        ]
+        let rr = ['read-only', 'workspace-write']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('extraArgs接於固定旗標之後', async function() {
+        let t = await dispatchCodex('abc', { exe: fake.exe, model: 'gpt-5.6-luna', extraArgs: ['--config', 'model_reasoning_effort="max"'] })
+        let o = JSON.parse(t.stdout)
+        let r = o.args
+        let rr = ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-m', 'gpt-5.6-luna', '--config', 'model_reasoning_effort="max"']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('prompt以stdin傳入, 中文與多行皆完整保留', async function() {
+        let prompt = '第一行中文\n第二行 with "quote" & <sym>\n第三行'
+        let t = await dispatchCodex(prompt, { exe: fake.exe })
+        let o = JSON.parse(t.stdout)
+        let r = [o.stdin === prompt, o.args.includes(prompt)]
+        let rr = [true, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('執行檔不存在時回傳ENOENT且不重試', async function() {
+        let t = await dispatchCodex('abc', { exe: 'codex-not-exist-for-test', maxRetries: 3 })
+        let r = [t.ok, t.error.includes('ENOENT'), t.attempts]
+        let rr = [false, true, 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('失敗時依maxRetries重試, 重試次數含初始共maxRetries+1次', async function() {
+        let t = await dispatchCodex('abc', { exe: fake.exe, extraArgs: ['--fake-exit=1'], maxRetries: 1, retryDelayMs: 100 })
+        let r = [t.ok, t.code, t.attempts]
+        let rr = [false, 1, 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('stderr內容原樣回傳', async function() {
+        let t = await dispatchCodex('abc', { exe: fake.exe, extraArgs: ['--fake-stderr=some warning'] })
+        let r = [t.ok, t.stderr]
+        let rr = [true, 'some warning']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchOpencode.test.mjs

@@ -0,0 +1,176 @@
+import assert from 'assert'
+import dispatchOpencode from '../src/dispatchOpencode.mjs'
+import createFakeCli from './tools/fakeCliForTest.mjs'
+
+
+describe('dispatchOpencode', function() {
+
+    let fake = null
+
+    before(function() {
+        fake = createFakeCli('fake-opencode')
+    })
+
+    after(function() {
+        if (fake) {
+            fake.clean()
+        }
+    })
+
+    it('prompt非有效字串時回傳錯誤結果物件且不reject', async function() {
+        let r = []
+        for (let prompt of [null, undefined, '', 123, {}, []]) {
+            let t = await dispatchOpencode(prompt)
+            r.push([t.ok, t.error, t.attempts])
+        }
+        let rr = [
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('固定帶run與--agent旗標, agent預設build', async function() {
+        let t = await dispatchOpencode('abc', { exe: fake.exe })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.args]
+        let rr = [true, ['run', '--agent', 'build']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('有給model時帶-m旗標', async function() {
+        let t = await dispatchOpencode('abc', { exe: fake.exe, model: 'opencode/deepseek-v4-flash-free' })
+        let o = JSON.parse(t.stdout)
+        let r = o.args
+        let rr = ['run', '--agent', 'build', '-m', 'opencode/deepseek-v4-flash-free']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('agent可自訂, 非有效字串則回退build', async function() {
+        let t1 = await dispatchOpencode('abc', { exe: fake.exe, agent: 'plan' })
+        let t2 = await dispatchOpencode('abc', { exe: fake.exe, agent: 123 })
+        let r = [
+            JSON.parse(t1.stdout).args[2],
+            JSON.parse(t2.stdout).args[2],
+        ]
+        let rr = ['plan', 'build']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('同時給予key與provider時注入OPENCODE_AUTH_CONTENT', async function() {
+        let t = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', key: 'sk-abc123' })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, JSON.parse(o.env.OPENCODE_AUTH_CONTENT)]
+        let rr = [true, { opencode: { type: 'api', key: 'sk-abc123' } }]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('僅給key或僅給provider時不注入OPENCODE_AUTH_CONTENT', async function() {
+        let t1 = await dispatchOpencode('abc', { exe: fake.exe, key: 'sk-abc123' })
+        let t2 = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode' })
+        let t3 = await dispatchOpencode('abc', { exe: fake.exe })
+        let r = [
+            JSON.parse(t1.stdout).env.OPENCODE_AUTH_CONTENT,
+            JSON.parse(t2.stdout).env.OPENCODE_AUTH_CONTENT,
+            JSON.parse(t3.stdout).env.OPENCODE_AUTH_CONTENT,
+        ]
+        let rr = ['', '', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('金鑰注入僅作用於當次子進程, 不影響本進程之process.env', async function() {
+        let before = process.env.OPENCODE_AUTH_CONTENT
+        let t = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', key: 'sk-abc123' })
+        let o = JSON.parse(t.stdout)
+        let after = process.env.OPENCODE_AUTH_CONTENT
+        let r = [o.env.OPENCODE_AUTH_CONTENT !== '', before === after]
+        let rr = [true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('逐次可帶不同金鑰, 供多把金鑰輪替', async function() {
+        let r = []
+        for (let key of ['sk-key1', 'sk-key2', 'sk-key3']) {
+            let t = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', key })
+            let o = JSON.parse(t.stdout)
+            r.push(JSON.parse(o.env.OPENCODE_AUTH_CONTENT).opencode.key)
+        }
+        let rr = ['sk-key1', 'sk-key2', 'sk-key3']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('config為物件時序列化後以OPENCODE_CONFIG_CONTENT注入', async function() {
+        let config = {
+            provider: {
+                'agnes-ai': {
+                    npm: '@ai-sdk/openai-compatible',
+                    name: 'Agnes',
+                    options: { baseURL: 'https://apihub.agnes-ai.com/v1' },
+                    models: { 'agnes-2.0-flash': { name: 'Agnes 2.0 Flash' } },
+                },
+            },
+        }
+        let t = await dispatchOpencode('abc', { exe: fake.exe, model: 'agnes-ai/agnes-2.0-flash', provider: 'agnes-ai', key: 'sk-abc123', config })
+        let o = JSON.parse(t.stdout)
+        let r = [
+            JSON.parse(o.env.OPENCODE_CONFIG_CONTENT),
+            JSON.parse(o.env.OPENCODE_AUTH_CONTENT),
+            o.args,
+        ]
+        let rr = [
+            config,
+            { 'agnes-ai': { type: 'api', key: 'sk-abc123' } },
+            ['run', '--agent', 'build', '-m', 'agnes-ai/agnes-2.0-flash'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('config為JSON字串時原樣注入', async function() {
+        let config = '{"provider":{"agnes-ai":{"npm":"@ai-sdk/openai-compatible"}}}'
+        let t = await dispatchOpencode('abc', { exe: fake.exe, config })
+        let o = JSON.parse(t.stdout)
+        let r = o.env.OPENCODE_CONFIG_CONTENT
+        let rr = config
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('config非有效物件或字串時不注入OPENCODE_CONFIG_CONTENT', async function() {
+        let r = []
+        for (let config of [null, undefined, '', 123, []]) {
+            let t = await dispatchOpencode('abc', { exe: fake.exe, config })
+            let o = JSON.parse(t.stdout)
+            r.push(o.env.OPENCODE_CONFIG_CONTENT)
+        }
+        let rr = ['', '', '', '', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('自帶env可與金鑰注入併存', async function() {
+        let t = await dispatchOpencode('abc', { exe: fake.exe, provider: 'opencode', key: 'sk-abc123', env: { FAKE_ENV: 'hello' } })
+        let o = JSON.parse(t.stdout)
+        let r = [o.env.FAKE_ENV, JSON.parse(o.env.OPENCODE_AUTH_CONTENT).opencode.key]
+        let rr = ['hello', 'sk-abc123']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('prompt以stdin傳入, 中文與多行皆完整保留', async function() {
+        let prompt = '第一行中文\n第二行 with "quote" & <sym>\n第三行'
+        let t = await dispatchOpencode(prompt, { exe: fake.exe })
+        let o = JSON.parse(t.stdout)
+        let r = [o.stdin === prompt, o.args.includes(prompt)]
+        let rr = [true, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('執行檔不存在時回傳ENOENT且不重試', async function() {
+        let t = await dispatchOpencode('abc', { exe: 'opencode-not-exist-for-test', maxRetries: 3 })
+        let r = [t.ok, t.error.includes('ENOENT'), t.attempts]
+        let rr = [false, true, 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-getCliArgs.test.mjs

@@ -0,0 +1,55 @@
+import assert from 'assert'
+import getCliArgs from '../src/getCliArgs.mjs'
+
+
+describe('getCliArgs', function() {
+
+    it('字串與陣列混合輸入可展平為一維陣列', function() {
+        let r = getCliArgs('run', ['--agent', 'build'], ['-m', 'opencode/abc'])
+        let rr = ['run', '--agent', 'build', '-m', 'opencode/abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('空陣列不產生任何參數', function() {
+        let r = getCliArgs('-p', [], '--verbose')
+        let rr = ['-p', '--verbose']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非有效字串之參數一律濾除', function() {
+        let r = getCliArgs('-p', undefined, null, 123, true, {}, '', '--verbose')
+        let rr = ['-p', '--verbose']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('僅濾除非有效字串, 不判斷旗標配對, 故可選旗標須由呼叫端整段給或不給', function() {
+        let r = [
+            getCliArgs('-p', ['--model', undefined]),
+            getCliArgs('-p', []),
+        ]
+        let rr = [
+            ['-p', '--model'],
+            ['-p'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('僅展開一層, 巢狀陣列內之陣列視為非字串而濾除', function() {
+        let r = getCliArgs('a', ['b', ['c', 'd'], 'e'])
+        let rr = ['a', 'b', 'e']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未給任何參數回傳空陣列', function() {
+        let r = getCliArgs()
+        let rr = []
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('保留參數原有順序與重複值', function() {
+        let r = getCliArgs('--config', 'a=1', ['--config', 'a=1'])
+        let rr = ['--config', 'a=1', '--config', 'a=1']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-getErrorResult.test.mjs

@@ -0,0 +1,45 @@
+import assert from 'assert'
+import getErrorResult from '../src/getErrorResult.mjs'
+
+
+describe('getErrorResult', function() {
+
+    it('回傳與execCli同結構之錯誤結果物件', function() {
+        let r = getErrorResult('something wrong')
+        let rr = {
+            ok: false,
+            stdout: '',
+            stderr: '',
+            code: null,
+            error: 'something wrong',
+            durationMs: 0,
+            attempts: 0,
+        }
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('鍵名與順序固定', function() {
+        let r = Object.keys(getErrorResult('abc'))
+        let rr = ['ok', 'stdout', 'stderr', 'code', 'error', 'durationMs', 'attempts']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非有效字串之錯誤訊息回退為unknown error', function() {
+        let r = []
+        for (let v of [null, undefined, '', 123, {}, []]) {
+            r.push(getErrorResult(v).error)
+        }
+        let rr = ['unknown error', 'unknown error', 'unknown error', 'unknown error', 'unknown error', 'unknown error']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('各次呼叫回傳互相獨立之物件', function() {
+        let a = getErrorResult('a')
+        let b = getErrorResult('b')
+        a.stdout = 'modified'
+        let r = [a === b, b.stdout, b.error]
+        let rr = [false, '', 'b']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/toolg/addVersion.mjs

@@ -0,0 +1,4 @@
+import addVersion from 'w-package-tools/src/addVersion.mjs'
+
+
+addVersion()

package/toolg/cleanFolder.mjs

@@ -0,0 +1,5 @@
+import cleanFolder from 'w-package-tools/src/cleanFolder.mjs'
+
+
+cleanFolder('dist')
+cleanFolder('docs')

package/toolg/gDistRollup.mjs

@@ -0,0 +1,24 @@
+import rollupFiles from 'w-package-tools/src/rollupFiles.mjs'
+import getFiles from 'w-package-tools/src/getFiles.mjs'
+
+
+let fdSrc = './src'
+let fdTar = './dist'
+
+
+rollupFiles({
+    fns: 'WDispatchAi.mjs',
+    fdSrc,
+    fdTar,
+    nameDistType: 'kebabCase',
+    globals: {
+        'path': 'path',
+        'fs': 'fs',
+        'child_process': 'child_process',
+    },
+    external: [
+        'path',
+        'fs',
+        'child_process',
+    ],
+})

package/toolg/modifyReadme.mjs

@@ -0,0 +1,4 @@
+import modifyReadme from 'w-package-tools/src/modifyReadme.mjs'
+
+
+modifyReadme()