@pikku/core 0.12.101 → 0.12.103

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 0.12.103
+
+### Patch Changes
+
+- 206dc04: `--json` now serialises the result of any command, not only the eleven that ship a renderer of their own.
+
+  The flag swapped in the JSON renderer only when a command-specific renderer existed, so on the other 94 commands it fell through to the program's default renderer — which prints forwarded log lines and drops anything else. `pikku info functions --json` therefore exited 0 and printed no JSON at all, which reads as "this command has no output" rather than as an unsupported flag.
+
+## 0.12.102
+
+### Patch Changes
+
+- f4e2e89: Add file attachments to `EmailService`.
+
+  `BaseSendEmailInput` gains an optional `attachments: EmailAttachment[]`, so it is
+  available on all three input variants — text, HTML and template. The new
+  `EmailAttachment` type is exported from `@pikku/core/services` alongside the
+  input types, and is shaped so that mapping it onto Resend, SendGrid, Nodemailer
+  or SES v2 is a straight field rename rather than a translation.
+
+  `content` is `Uint8Array | string`, where a string is always read as base64.
+  Both forms are accepted because both are what callers already hold: bytes come
+  out of a fetch or a file read, and base64 comes out of a database column or a
+  provider API. `Buffer` is deliberately absent from the type — it is a subclass
+  of `Uint8Array`, so Node callers can still pass one, while the type stays usable
+  in Cloudflare Workers, where `Buffer` does not exist.
+
+  `LocalEmailService` now logs attachment metadata — filename, content type,
+  content id, disposition and content length — instead of dropping the field
+  silently. The content itself is deliberately not logged.
+
+  The template-rendering wrapper documented in the emails skill rebuilt its
+  delegate payload field by field and therefore dropped `attachments`; it now
+  forwards them.
+
 ## 0.12.101
 
 ### Patch Changes

package/dist/services/email-service.d.ts

@@ -4,6 +4,18 @@ export interface EmailTemplateReference {
     locale?: string;
     data?: Record<string, unknown>;
 }
+export interface EmailAttachment {
+    filename: string;
+    /**
+     * Raw bytes, or the content already base64-encoded. A `string` is always
+     * read as base64 — never as a plain-text body — so text attachments must be
+     * encoded by the caller.
+     */
+    content: Uint8Array | string;
+    contentType?: string;
+    contentId?: string;
+    disposition?: 'attachment' | 'inline';
+}
 export interface BaseSendEmailInput {
     to: string | string[];
     from?: string;
@@ -12,6 +24,7 @@ export interface BaseSendEmailInput {
     replyTo?: string | string[];
     headers?: Record<string, string>;
     subject?: string;
+    attachments?: EmailAttachment[];
 }
 export interface SendTextEmailInput extends BaseSendEmailInput {
     text: string;

package/dist/services/index.d.ts

@@ -20,7 +20,7 @@ export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary,
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
 export type { JWTService } from './jwt-service.js';
-export type { EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
+export type { EmailAttachment, EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { renderEmail, type EmailAssets, type EmailTemplateAssets, type EmailTemplateHashes, type RenderEmailRequest, type RenderedEmailResult, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
 export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';

package/dist/services/local-email-service.js

@@ -20,6 +20,15 @@ export class LocalEmailService {
         if ('text' in input && typeof input.text === 'string') {
             payload.textLength = input.text.length;
         }
+        if (input.attachments?.length) {
+            payload.attachments = input.attachments.map((attachment) => ({
+                filename: attachment.filename,
+                contentType: attachment.contentType ?? null,
+                contentId: attachment.contentId ?? null,
+                disposition: attachment.disposition ?? 'attachment',
+                contentLength: attachment.content.length,
+            }));
+        }
         console.info(JSON.stringify(payload));
         return {};
     }

package/dist/wirings/cli/cli-runner.js

@@ -245,7 +245,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             const commandRenderer = programData?.renderers[commandId];
             const jsonMode = data.json === true ||
                 data.output === 'json';
-            const finalRenderer = jsonMode && commandRenderer !== undefined
+            const finalRenderer = jsonMode
                 ? defaultJSONRenderer
                 : (commandRenderer ?? programData?.defaultRenderer);
             if (finalRenderer !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.101",
+  "version": "0.12.103",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -39,6 +39,11 @@ const skipped = new Set([
   'build',
   '.git',
   'coverage',
+  // Agent scratch worktrees are whole Pikku projects generated by whatever CLI
+  // version happened to scaffold them, so discovery finds them and reports a
+  // barrel this repo does not own. They are gitignored and belong to no
+  // workspace, which is what makes them out of scope rather than merely noisy.
+  '.claude',
 ])
 
 const findProjects = (dir: string, out: string[] = []): string[] => {

package/src/ecosystem-tier-removed.test.ts

@@ -15,6 +15,9 @@ const skipped = new Set([
   '.git',
   '.deploy',
   'coverage',
+  // A worktree here carries its own copy of this file, which necessarily
+  // contains the specifier being scanned for — the guard would report itself.
+  '.claude',
 ])
 
 const collectSourceFiles = (

package/src/no-root-barrel.test.ts

@@ -22,11 +22,19 @@ const skipDirectory = new Set([
   '.git',
   'build',
   'coverage',
+  // Agent scratch worktrees are whole Pikku projects scaffolded by whatever CLI
+  // version happened to write them, so they carry specifiers this repo does not
+  // own. They are gitignored and belong to no workspace, which is what puts them
+  // out of scope rather than merely making them noisy.
+  '.claude',
 ])
 
+/** A verifier's scratch project, left behind by a run that did not clean up. */
+const isScratchProject = (entry: string) => entry.startsWith('.tmp-')
+
 const walk = (dir: string, out: string[] = []): string[] => {
   for (const entry of readdirSync(dir)) {
-    if (skipDirectory.has(entry)) continue
+    if (skipDirectory.has(entry) || isScratchProject(entry)) continue
     const path = join(dir, entry)
     if (statSync(path).isDirectory()) walk(path, out)
     else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)

package/src/services/email-service.test.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import type {
+  EmailAttachment,
+  EmailService,
+  SendEmailInput,
+  SendEmailResult,
+  SendHTMLEmailInput,
+  SendTemplateEmailInput,
+  SendTextEmailInput,
+} from './email-service.js'
+
+const receipt: EmailAttachment = {
+  filename: 'receipt.pdf',
+  content: new Uint8Array([1, 2, 3]),
+  contentType: 'application/pdf',
+}
+
+const logo: EmailAttachment = {
+  filename: 'logo.png',
+  content: 'aGVsbG8=',
+  contentType: 'image/png',
+  contentId: 'logo',
+  disposition: 'inline',
+}
+
+test('a text email carries attachments', () => {
+  const input: SendTextEmailInput = {
+    to: 'user@example.com',
+    text: 'Your receipt is attached',
+    attachments: [receipt],
+  }
+
+  assert.deepEqual(input.attachments, [receipt])
+})
+
+test('an html email carries attachments', () => {
+  const input: SendHTMLEmailInput = {
+    to: 'user@example.com',
+    html: '<img src="cid:logo" />',
+    attachments: [logo],
+  }
+
+  assert.equal(input.attachments?.[0]?.disposition, 'inline')
+  assert.equal(input.attachments?.[0]?.contentId, 'logo')
+})
+
+test('a template email carries attachments', () => {
+  const input: SendTemplateEmailInput = {
+    to: 'user@example.com',
+    template: { name: 'receipt', locale: 'en', data: { total: 10 } },
+    attachments: [receipt, logo],
+  }
+
+  assert.equal(input.attachments?.length, 2)
+})
+
+test('attachments are optional on every variant', () => {
+  const inputs: SendEmailInput[] = [
+    { to: 'user@example.com', text: 'hello' },
+    { to: 'user@example.com', html: '<p>hello</p>' },
+    { to: 'user@example.com', template: { name: 'welcome' } },
+  ]
+
+  for (const input of inputs) {
+    assert.equal(input.attachments, undefined)
+  }
+})
+
+test('a wrapping service forwards attachments to its delegate', async () => {
+  const sent: SendEmailInput[] = []
+  const delegate: EmailService = {
+    async send(input): Promise<SendEmailResult> {
+      sent.push(input as SendEmailInput)
+      return { messageId: 'delegated' }
+    },
+  }
+
+  const wrapper: EmailService = {
+    async send(input): Promise<SendEmailResult> {
+      const { template, ...rest } = input as SendTemplateEmailInput
+      return delegate.send({
+        ...rest,
+        subject: `rendered:${template.name}`,
+        html: '<p>rendered</p>',
+      })
+    },
+  }
+
+  const result = await wrapper.send({
+    to: 'user@example.com',
+    template: { name: 'receipt' },
+    attachments: [receipt],
+  })
+
+  assert.equal(result.messageId, 'delegated')
+  assert.equal(sent.length, 1)
+  assert.deepEqual(sent[0]!.attachments, [receipt])
+})

package/src/services/email-service.ts

@@ -6,6 +6,19 @@ export interface EmailTemplateReference {
   data?: Record<string, unknown>
 }
 
+export interface EmailAttachment {
+  filename: string
+  /**
+   * Raw bytes, or the content already base64-encoded. A `string` is always
+   * read as base64 — never as a plain-text body — so text attachments must be
+   * encoded by the caller.
+   */
+  content: Uint8Array | string
+  contentType?: string
+  contentId?: string
+  disposition?: 'attachment' | 'inline'
+}
+
 export interface BaseSendEmailInput {
   to: string | string[]
   from?: string
@@ -14,6 +27,7 @@ export interface BaseSendEmailInput {
   replyTo?: string | string[]
   headers?: Record<string, string>
   subject?: string
+  attachments?: EmailAttachment[]
 }
 
 export interface SendTextEmailInput extends BaseSendEmailInput {

package/src/services/index.ts

@@ -46,6 +46,7 @@ export type {
 // knowledge: decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md
 export type { JWTService } from './jwt-service.js'
 export type {
+  EmailAttachment,
   EmailService,
   SendEmailInput,
   SendEmailResult,

package/src/services/local-email-service.test.ts

@@ -106,3 +106,77 @@ test('LocalEmailService logs null textLength for HTML email without plain text',
   assert.equal(payload.htmlLength, '<p>Hello</p>'.length)
   assert.equal(payload.textLength, null)
 })
+
+test('LocalEmailService logs attachment metadata without the content', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({
+      to: 'user@example.com',
+      html: '<img src="cid:logo" />',
+      attachments: [
+        {
+          filename: 'receipt.pdf',
+          content: new Uint8Array([1, 2, 3, 4]),
+          contentType: 'application/pdf',
+        },
+        {
+          filename: 'logo.png',
+          content: 'aGVsbG8=',
+          contentType: 'image/png',
+          contentId: 'logo',
+          disposition: 'inline',
+        },
+      ],
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  const payload = JSON.parse(writes[0])
+  assert.deepEqual(payload.attachments, [
+    {
+      filename: 'receipt.pdf',
+      contentType: 'application/pdf',
+      contentId: null,
+      disposition: 'attachment',
+      contentLength: 4,
+    },
+    {
+      filename: 'logo.png',
+      contentType: 'image/png',
+      contentId: 'logo',
+      disposition: 'inline',
+      contentLength: 8,
+    },
+  ])
+  assert.equal(writes[0].includes('aGVsbG8='), false)
+})
+
+test('LocalEmailService omits attachments when there are none', async () => {
+  const service = new LocalEmailService()
+  const writes: string[] = []
+  const originalInfo = console.info
+  console.info = (value?: unknown) => {
+    writes.push(String(value))
+  }
+
+  try {
+    await service.send({ to: 'user@example.com', text: 'no files' })
+    await service.send({
+      to: 'user@example.com',
+      text: 'no files',
+      attachments: [],
+    })
+  } finally {
+    console.info = originalInfo
+  }
+
+  assert.equal(JSON.parse(writes[0]).attachments, undefined)
+  assert.equal(JSON.parse(writes[1]).attachments, undefined)
+})

package/src/services/local-email-service.ts

@@ -27,6 +27,15 @@ export class LocalEmailService implements EmailService {
     if ('text' in input && typeof input.text === 'string') {
       payload.textLength = input.text.length
     }
+    if (input.attachments?.length) {
+      payload.attachments = input.attachments.map((attachment) => ({
+        filename: attachment.filename,
+        contentType: attachment.contentType ?? null,
+        contentId: attachment.contentId ?? null,
+        disposition: attachment.disposition ?? 'attachment',
+        contentLength: attachment.content.length,
+      }))
+    }
 
     console.info(JSON.stringify(payload))
     return {}

package/src/wirings/cli/cli-runner.test.ts

@@ -829,4 +829,141 @@ describe('CLI Runner', () => {
       assert.ok(printed.includes('at '))
     })
   })
+  describe('--json output', () => {
+    const wireGreet = (renderers: Record<string, any>, defaultRenderer: any) => {
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet',
+                pikkuFuncId: 'greetFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState(null, 'cli', 'programs', {
+        'test-cli': { defaultRenderer, middleware: [], renderers },
+      })
+
+      pikkuState(null, 'function', 'meta', {
+        greetFunc: {
+          pikkuFuncId: 'greetFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+          sessionless: true,
+        },
+      })
+
+      addFunction('greetFunc', {
+        func: async () => ({ name: 'Alice' }),
+        auth: false,
+      })
+    }
+
+    const captureStdout = async (fn: () => Promise<unknown>) => {
+      const lines: string[] = []
+      const original = console.log
+      console.log = (...args: unknown[]) => {
+        lines.push(args.map(String).join(' '))
+      }
+      try {
+        await fn()
+      } finally {
+        console.log = original
+      }
+      return lines
+    }
+
+    test('serialises the result for a command with no renderer of its own', async () => {
+      const textOnly = () => {}
+      wireGreet({}, textOnly)
+
+      const lines = await captureStdout(() =>
+        runCLICommand({
+          program: 'test-cli',
+          commandPath: ['greet'],
+          data: { json: true },
+          singletonServices,
+          createWireServices,
+        })
+      )
+
+      assert.deepEqual(lines, ['{"name":"Alice"}'])
+    })
+
+    test('--output json is equivalent to --json', async () => {
+      const textOnly = () => {}
+      wireGreet({}, textOnly)
+
+      const lines = await captureStdout(() =>
+        runCLICommand({
+          program: 'test-cli',
+          commandPath: ['greet'],
+          data: { output: 'json' },
+          singletonServices,
+          createWireServices,
+        })
+      )
+
+      assert.deepEqual(lines, ['{"name":"Alice"}'])
+    })
+
+    test('json overrides a command renderer', async () => {
+      let renderedWith: unknown
+      wireGreet(
+        {
+          greet: (_s: any, data: any) => {
+            renderedWith = data
+          },
+        },
+        () => {}
+      )
+
+      const lines = await captureStdout(() =>
+        runCLICommand({
+          program: 'test-cli',
+          commandPath: ['greet'],
+          data: { json: true },
+          singletonServices,
+          createWireServices,
+        })
+      )
+
+      assert.equal(renderedWith, undefined)
+      assert.deepEqual(lines, ['{"name":"Alice"}'])
+    })
+
+    test('without json the command renderer still wins', async () => {
+      let renderedWith: unknown
+      wireGreet(
+        {
+          greet: (_s: any, data: any) => {
+            renderedWith = data
+          },
+        },
+        () => {}
+      )
+
+      const lines = await captureStdout(() =>
+        runCLICommand({
+          program: 'test-cli',
+          commandPath: ['greet'],
+          data: {},
+          singletonServices,
+          createWireServices,
+        })
+      )
+
+      assert.deepEqual(renderedWith, { name: 'Alice' })
+      assert.deepEqual(lines, [])
+    })
+  })
 })

package/src/wirings/cli/cli-runner.ts

@@ -391,10 +391,9 @@ export async function runCLICommand({
       const jsonMode =
         (data as { json?: unknown; output?: unknown }).json === true ||
         (data as { json?: unknown; output?: unknown }).output === 'json'
-      const finalRenderer: CorePikkuCLIRender<any> | undefined =
-        jsonMode && commandRenderer !== undefined
-          ? defaultJSONRenderer
-          : (commandRenderer ?? programData?.defaultRenderer)
+      const finalRenderer: CorePikkuCLIRender<any> | undefined = jsonMode
+        ? defaultJSONRenderer
+        : (commandRenderer ?? programData?.defaultRenderer)
       if (finalRenderer !== undefined) {
         await Promise.resolve(
           finalRenderer(