fix: preserve argc result output delivery

Author: ethan-huo

docs/spec-7.0-behavior.md

@@ -246,6 +246,11 @@ Scenario: multiline string field → block scalar
 Scenario: handler stdout writes do not pollute the result
   Given a handler that console.log("debug") then returns { ok: true }
   Then stdout = "ok: true\n"   (the console.log went to stderr)
+
+Scenario: the result write respects downstream lifecycle
+  Given a handler returns a result larger than the stdout buffer
+  Then argc waits for the result write to complete before returning
+  And an EPIPE from a downstream reader that closes early is a successful terminal path
 ```
 
 ---

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "argc",
-	"version": "7.7.0",
+	"version": "7.7.1",
 	"type": "module",
 	"types": "./dist/index.d.ts",
 	"exports": {

skills/argc/SKILL.md

@@ -33,7 +33,7 @@ Rendered layout:
 
 ```
 templates/main.ts       -> src/main.ts
-templates/main.test.ts  -> src/main.test.ts
+templates/main.test.ts.tpl -> src/main.test.ts
 templates/package.json  -> package.json
 templates/tsconfig.json -> tsconfig.json
 templates/ci.yml        -> .github/workflows/ci.yml

skills/argc/references/output.md

@@ -67,15 +67,15 @@ For stdout _summaries_, prefer YAML:
 Raw data is the exception, not the default: expose it behind `--json` so the agent
 can pipe it through `jq`, and keep the default human/agent-facing path as a summary.
 
-## Serializing: use the `yaml` library, not `Bun.YAML`
+## Serialization
 
-```typescript
-import { stringify } from 'yaml' // npm: yaml (eemeli/yaml), the js-yaml successor
+Return the result and let argc own stdout:
 
-process.stdout.write(stringify(value))
+```typescript
+return value
 ```
 
-Why not `Bun.YAML.stringify`: its native serializer never emits `|` literal-block
+argc uses the `yaml` library rather than `Bun.YAML.stringify`: Bun's native serializer never emits `|` literal-block
 scalars — multi-line strings come out as double-quoted with escaped `\n`
 (`preview: "<div>\n  ..."`). That is intentional and test-locked in Bun through
 1.4, not a version gap that will close (the `|`/`>` support in Bun's YAML docs is
@@ -189,18 +189,17 @@ async fetch({ input }) {
   await Bun.write(path, JSON.stringify(records))       // persist bulk to state dir
 
   if (input.json) {                                    // --json: raw to the pipe
-    process.stdout.write(JSON.stringify(records))
-    return
+    return JSON.stringify(records)
   }
 
-  process.stdout.write(stringify({                     // default: summary to stdout
+  return {                                             // argc serializes this summary to stdout
     records: records.length,
     written: path,
     $hints: [
       `Records at ${path} — slice with: jq '.[0:10]' ${path}`,
       'Re-run with --json to stream raw records to a pipe',
     ],
-  }))
+  }
 }
 ```
 

skills/argc/scripts/argc-start.sh

@@ -85,7 +85,7 @@ render() {
 }
 
 render main.ts src/main.ts
-render main.test.ts src/main.test.ts
+render main.test.ts.tpl src/main.test.ts
 render package.json package.json
 render tsconfig.json tsconfig.json
 render ci.yml .github/workflows/ci.yml

skills/argc/templates/main.test.ts skills/argc/templates/main.test.ts.tplskills/argc/templates/main.test.ts renamed to skills/argc/templates/main.test.ts.tpl

@@ -1,11 +1,7 @@
 import { expect, test } from 'bun:test'
 import { join } from 'node:path'
 
-// Run the scaffolded entry in place. This file is copied verbatim into a new
-// project, so it must not reach outside that project's own src/ — an earlier
-// version assembled a throwaway project three directories up and symlinked its
-// root in as `argc`, which is how argc verifies its own template, not how a
-// downstream CLI tests itself.
+// Exercise the same entry point and dependency graph users install.
 const ENTRY = join(import.meta.dir, 'main.ts')
 
 async function run(...args: string[]) {

src/cli.ts

@@ -32,6 +32,7 @@ import {
 	formatRuntimeError,
 	renderError,
 	renderResult,
+	writeOutput,
 	type ErrorEnvelope,
 	type ErrorIssue,
 	withStdoutRerouted,
@@ -161,7 +162,7 @@ export class CLI<
 			runOptions.handlers as Record<string, unknown>,
 			parsed.raw,
 		)
-		process.stdout.write(renderResult(result))
+		await writeOutput(process.stdout, renderResult(result))
 	}
 
 	private async runBuiltin(

src/render.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test'
+import { Writable } from 'node:stream'
+
+import { writeOutput } from './render'
+
+describe('writeOutput', () => {
+	test('waits until the stream accepts the complete result', async () => {
+		let completed = false
+		const stream = new Writable({
+			write(_chunk, _encoding, callback) {
+				setTimeout(() => {
+					completed = true
+					callback()
+				}, 5)
+			},
+		})
+
+		await writeOutput(stream, 'result')
+
+		expect(completed).toBe(true)
+	})
+
+	test('treats a downstream EPIPE as a completed write', async () => {
+		const stream = new Writable({
+			write(_chunk, _encoding, callback) {
+				const error = Object.assign(new Error('closed'), { code: 'EPIPE' })
+				callback(error)
+			},
+		})
+
+		await expect(writeOutput(stream, 'result')).resolves.toBeUndefined()
+	})
+})

src/render.ts

@@ -1,3 +1,5 @@
+import type { Writable } from 'node:stream'
+
 import { stringify } from 'yaml'
 
 import { colorizeError } from './markup'
@@ -121,6 +123,38 @@ export function renderError(envelope: ErrorEnvelope): string {
 	return colorizeError(stringify(normalizeValue(envelope), { lineWidth: 0 }))
 }
 
+const brokenPipes = new WeakSet<Writable>()
+
+export function writeOutput(stream: Writable, value: string): Promise<void> {
+	if (value === '' || brokenPipes.has(stream)) return Promise.resolve()
+
+	return new Promise((resolve, reject) => {
+		let settled = false
+		const finish = (error?: Error | null) => {
+			if (settled) return
+			settled = true
+			stream.off('error', finish)
+
+			if (error && 'code' in error && error.code === 'EPIPE') {
+				// A downstream reader may intentionally close early; the producer has
+				// completed its contract once the pipe stops accepting output.
+				brokenPipes.add(stream)
+				stream.once('error', () => {})
+				resolve()
+				return
+			}
+			if (error) {
+				reject(error)
+				return
+			}
+			resolve()
+		}
+
+		stream.once('error', finish)
+		stream.write(value, finish)
+	})
+}
+
 export async function withStdoutRerouted<T>(fn: () => Promise<T>): Promise<T> {
 	const originalWrite = process.stdout.write
 	const originalConsoleLog = console.log

src/v7.test.ts

@@ -53,8 +53,12 @@ async function capture(
 		envEntries.map(([key]) => [key, process.env[key]] as const),
 	)
 
-	process.stdout.write = ((chunk: string | Uint8Array) => {
+	process.stdout.write = ((
+		chunk: string | Uint8Array,
+		callback?: (error?: Error | null) => void,
+	) => {
 		stdout += String(chunk)
+		callback?.()
 		return true
 	}) as typeof process.stdout.write
 	process.stderr.write = ((chunk: string | Uint8Array) => {