@stacksjs/defaults 0.75.40 → 0.75.42

package/ide/vscode/scripts/stx-contributes.ts

@@ -0,0 +1,66 @@
+/**
+ * Keeps the stx half of package.json's `contributes` equal to what
+ * `@stacksjs/stx-vscode` ships.
+ *
+ * VS Code reads languages, grammars, commands and settings only from the
+ * manifest, so the built-in stx support needs them declared here, pointing at
+ * dist/stx/ (copied there by build.ts). The library describes them in
+ * `contributes.json`; this derives the manifest from it rather than keeping a
+ * second copy by hand. Snippets are left out on purpose: the extension offers
+ * them as completions only when the stx extension is not installed, because
+ * a manifest entry would show every snippet twice next to it.
+ *
+ *   bun scripts/stx-contributes.ts --write   update package.json (`bun run sync:stx`)
+ *
+ * tests/manifest.test.ts fails while the two disagree.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import process from 'node:process'
+
+export interface StxContributes {
+  languages: Array<Record<string, unknown> & { id: string, configuration: string }>
+  grammars: Array<Record<string, unknown> & { language: string, path: string }>
+  commands: Array<{ command: string, title: string, category?: string }>
+  configuration: { title: string, properties: Record<string, unknown> }
+}
+
+const STX_DIR = './dist/stx/'
+
+function fromStx(path: string): string {
+  return STX_DIR + path.replace(/^\.\//, '')
+}
+
+/** `manifest` with its stx contributions replaced by the library's. */
+export function withStxContributes(manifest: any, stx: StxContributes): any {
+  const stxCommands = new Set(stx.commands.map(command => command.command))
+  const contributes = manifest.contributes
+  const sections: Array<{ title: string }> = Array.isArray(contributes.configuration) ? contributes.configuration : [contributes.configuration]
+
+  return {
+    ...manifest,
+    contributes: {
+      ...contributes,
+      languages: stx.languages.map(language => ({ ...language, configuration: fromStx(language.configuration) })),
+      grammars: stx.grammars.map(grammar => ({ ...grammar, path: fromStx(grammar.path) })),
+      commands: [...contributes.commands.filter((command: { command: string }) => !stxCommands.has(command.command)), ...stx.commands],
+      configuration: [...sections.filter(section => section.title !== stx.configuration.title), stx.configuration],
+    },
+  }
+}
+
+export function libraryContributes(root: string): StxContributes {
+  return JSON.parse(readFileSync(Bun.resolveSync('@stacksjs/stx-vscode/contributes.json', root), 'utf8'))
+}
+
+if (import.meta.main) {
+  const root = join(import.meta.dir, '..')
+  const path = join(root, 'package.json')
+  const manifest = JSON.parse(readFileSync(path, 'utf8'))
+  const next = `${JSON.stringify(withStxContributes(manifest, libraryContributes(root)), null, 2)}\n`
+
+  if (process.argv.includes('--write'))
+    writeFileSync(path, next)
+  else
+    process.stdout.write(next)
+}

package/ide/vscode/src/env-file.ts

@@ -0,0 +1,103 @@
+/**
+ * Env files, read the way Stacks reads them - the pure half of ./env.ts.
+ *
+ * Decryption and key lookup are not reimplemented here: they are
+ * `@stacksjs/env`'s own (core/env/src), bundled into the extension, so a value
+ * the hover decrypts is exactly what `./buddy env:get` prints.
+ */
+import { basename } from 'node:path'
+import { envPrivateKeyNames } from '../../../../core/env/src/cli'
+import { decryptValue } from '../../../../core/env/src/crypto'
+import { parseEnvFile } from './project'
+
+/** `.env`, `.env.local`, `.env.production`, ... - not `.env.keys`, which holds the private keys themselves. */
+export function isEnvFile(path: string): boolean {
+  const name = basename(path)
+  return /^\.env(?:\..+)?$/.test(name) && name !== '.env.keys'
+}
+
+export function isEncrypted(value: string): boolean {
+  return value.startsWith('encrypted:')
+}
+
+export interface EnvEntry {
+  key: string
+  value: string
+  /** Character offsets of the value on its line, quotes excluded. */
+  start: number
+  end: number
+}
+
+/** The `KEY=value` on one line, with where its value sits, by `parseEnvFile`'s rules. */
+export function envEntryAt(line: string): EnvEntry | undefined {
+  const match = line.match(/^(\s*(?:export\s+)?([A-Z_a-z][\w.-]*)\s*=\s*)(.*)$/)
+  if (!match)
+    return undefined
+
+  const key = match[2] as string
+  const value = parseEnvFile(line)[key]
+  if (value === undefined)
+    return undefined
+
+  const rest = match[3] as string
+  const quoted = rest[0] === '"' || rest[0] === '\'' || rest[0] === '`'
+  const start = (match[1] as string).length + (quoted ? 1 : 0)
+  return { key, value, start, end: start + value.length }
+}
+
+/** Keys `.env.example` declares that the env file does not set, in example order. */
+export function missingKeys(example: string, actual: string): string[] {
+  const present = parseEnvFile(actual)
+  return Object.keys(parseEnvFile(example)).filter(key => !(key in present))
+}
+
+export interface PrivateKey {
+  name: string
+  key: string
+  from: '.env.keys' | 'environment'
+}
+
+/**
+ * The private key for an env file, looked up as `./buddy env:get` does:
+ * `envPrivateKeyNames` (`DOTENV_PRIVATE_KEY_<ENV>`, then `DOTENV_PRIVATE_KEY`)
+ * in `.env.keys`, then in the environment, the dotenvx convention for CI and
+ * servers where `.env.keys` must not exist.
+ */
+export function findPrivateKey(envFile: string, keysFile: string | undefined, environment: Record<string, string | undefined>): PrivateKey | undefined {
+  const names = envPrivateKeyNames(basename(envFile))
+  const keys = keysFile === undefined ? {} : parseEnvFile(keysFile)
+
+  for (const name of names) {
+    if (keys[name])
+      return { name, key: keys[name] as string, from: '.env.keys' }
+  }
+  for (const name of names) {
+    if (environment[name])
+      return { name, key: environment[name] as string, from: 'environment' }
+  }
+  return undefined
+}
+
+export type Decryption =
+  | { ok: true, value: string, key: PrivateKey }
+  | { ok: false, reason: 'no-key', looked: string[] }
+  | { ok: false, reason: 'failed', key: PrivateKey }
+
+/** Decrypt one value in memory. The result is never cached or written anywhere. */
+export function decryptEnvValue(
+  envFile: string,
+  value: string,
+  keysFile: string | undefined,
+  environment: Record<string, string | undefined>,
+): Decryption {
+  const key = findPrivateKey(envFile, keysFile, environment)
+  if (!key)
+    return { ok: false, reason: 'no-key', looked: envPrivateKeyNames(basename(envFile)) }
+
+  try {
+    return { ok: true, value: decryptValue(value, key.key), key }
+  }
+  catch {
+    return { ok: false, reason: 'failed', key }
+  }
+}

package/ide/vscode/src/env.ts

@@ -0,0 +1,241 @@
+/**
+ * Stacks env files, built in: decrypted values on hover, keys missing against
+ * `.env.example`, and the `buddy env:*` commands from the Command Palette.
+ *
+ * Plaintext only ever exists in memory and on screen. The hover decrypts with
+ * `@stacksjs/env`'s own code (./env-file.ts) and nothing is cached, logged or
+ * written; the commands run the project's `./buddy` directly (no shell, so a
+ * value typed for `env:set` does not land in shell history).
+ */
+import type * as vscode from 'vscode'
+import { basename, dirname, join, relative } from 'node:path'
+import { decryptEnvValue, envEntryAt, isEncrypted, isEnvFile, missingKeys } from './env-file'
+
+type Vscode = typeof vscode
+
+export interface EnvHost {
+  exists: (path: string) => boolean
+  read: (path: string) => string | undefined
+  exec: (file: string, args: string[], cwd: string) => Promise<string>
+  environment: Record<string, string | undefined>
+}
+
+export const ENV_COMMANDS = {
+  get: 'stacks.env.get',
+  set: 'stacks.env.set',
+  encrypt: 'stacks.env.encrypt',
+  decrypt: 'stacks.env.decrypt',
+  rotate: 'stacks.env.rotate',
+} as const
+
+function isProject(host: EnvHost, folder: string): boolean {
+  return host.exists(join(folder, 'buddy')) || host.exists(join(folder, 'config', 'app.ts'))
+}
+
+/**
+ * The `.env.keys` for an env file: beside it, else at the project root, where
+ * `./buddy env:*` looks for it.
+ */
+export function keysFileFor(host: EnvHost, envFile: string, root: string | undefined): string | undefined {
+  for (const dir of [dirname(envFile), root]) {
+    if (!dir)
+      continue
+    const source = host.read(join(dir, '.env.keys'))
+    if (source !== undefined)
+      return source
+  }
+  return undefined
+}
+
+/**
+ * A decryptor for `loadProjectEnv`, so the preview can read an encrypted
+ * `APP_URL` or `PORT` with the same keys the hover uses.
+ */
+export function projectDecryptor(host: EnvHost, root: string): (file: string, value: string) => string | undefined {
+  return (file, value) => {
+    const path = join(root, file)
+    const result = decryptEnvValue(path, value, keysFileFor(host, path, root), host.environment)
+    return result.ok ? result.value : undefined
+  }
+}
+
+export function createEnvSupport(api: Vscode, host: EnvHost): {
+  activate: (context: { subscriptions: Array<{ dispose: () => unknown }> }) => void
+} {
+  const diagnostics = api.languages.createDiagnosticCollection('stacks-env')
+  const settings = () => api.workspace.getConfiguration('stacks')
+
+  function rootFor(uri: vscode.Uri): string | undefined {
+    const folder = api.workspace.getWorkspaceFolder(uri)?.uri.fsPath
+    return folder && isProject(host, folder) ? folder : undefined
+  }
+
+  function projectRoot(): string | undefined {
+    const active = api.window.activeTextEditor?.document.uri
+    const fromActive = active ? rootFor(active) : undefined
+    if (fromActive)
+      return fromActive
+    return (api.workspace.workspaceFolders ?? []).map(folder => folder.uri.fsPath).find(folder => isProject(host, folder))
+  }
+
+  const hover: vscode.HoverProvider = {
+    provideHover(document, position) {
+      if (!isEnvFile(document.uri.fsPath) || !settings().get<boolean>('env.decryptOnHover', true))
+        return undefined
+
+      const entry = envEntryAt(document.lineAt(position.line).text)
+      if (!entry || !isEncrypted(entry.value) || position.character < entry.start - 1 || position.character > entry.end + 1)
+        return undefined
+
+      const root = rootFor(document.uri)
+      const result = decryptEnvValue(document.uri.fsPath, entry.value, keysFileFor(host, document.uri.fsPath, root), host.environment)
+      const markdown = new api.MarkdownString()
+      const range = new api.Range(position.line, entry.start, position.line, entry.end)
+
+      if (result.ok) {
+        markdown.appendMarkdown(`**${entry.key}**, decrypted with \`${result.key.name}\` from ${result.key.from === '.env.keys' ? '`.env.keys`' : 'the environment'}:`)
+        markdown.appendCodeblock(result.value, 'text')
+      }
+      else if (result.reason === 'no-key') {
+        markdown.appendMarkdown(`**${entry.key}** is encrypted. No private key to decrypt it: looked for ${result.looked.map(name => `\`${name}\``).join(' and ')} in \`.env.keys\` and the environment.`)
+      }
+      else {
+        markdown.appendMarkdown(`**${entry.key}** did not decrypt with \`${result.key.name}\`. The value or the key is wrong, or it was encrypted for another key.`)
+      }
+
+      return new api.Hover(markdown, range)
+    },
+  }
+
+  function checkMissingKeys(document: vscode.TextDocument): void {
+    const path = document.uri.fsPath
+    if (basename(path) === '.env.example') {
+      const env = api.workspace.textDocuments.find(open => open.uri.fsPath === join(dirname(path), '.env'))
+      if (env)
+        checkMissingKeys(env)
+      return
+    }
+
+    if (basename(path) !== '.env' || !settings().get<boolean>('env.missingKeys', true)) {
+      diagnostics.delete(document.uri)
+      return
+    }
+
+    const example = host.read(join(dirname(path), '.env.example'))
+    if (example === undefined) {
+      diagnostics.delete(document.uri)
+      return
+    }
+
+    const top = new api.Range(0, 0, 0, Math.max(document.lineAt(0).text.length, 1))
+    diagnostics.set(document.uri, missingKeys(example, document.getText()).map((key) => {
+      const diagnostic = new api.Diagnostic(top, `${key} is in .env.example but not set here.`, api.DiagnosticSeverity.Information)
+      diagnostic.source = 'stacks'
+      diagnostic.code = 'missing-env-key'
+      return diagnostic
+    }))
+  }
+
+  /** The env file a command acts on: the open one, or `.env`. */
+  function targetFile(root: string): string {
+    const active = api.window.activeTextEditor?.document.uri.fsPath
+    return active && isEnvFile(active) && !relative(root, active).startsWith('..') ? relative(root, active) : '.env'
+  }
+
+  async function buddy(root: string, args: string[]): Promise<string | undefined> {
+    try {
+      return await host.exec(join(root, 'buddy'), args, root)
+    }
+    catch (error) {
+      // The error carries the command's stderr, never the value: values are
+      // only ever arguments, and execFile does not echo arguments.
+      void api.window.showErrorMessage(`Stacks: ./buddy ${args[0]} failed. ${error instanceof Error ? error.message.split('\n')[0] : ''}`)
+      return undefined
+    }
+  }
+
+  async function askKey(root: string, file: string, prompt: string): Promise<string | undefined> {
+    const keys = Object.keys(parseKeys(host.read(join(root, file))))
+    if (keys.length) {
+      const picked = await api.window.showQuickPick(keys, { title: `${prompt} (${file})`, placeHolder: 'Key' })
+      return picked
+    }
+    return (await api.window.showInputBox({ title: `${prompt} (${file})`, prompt: 'Key' }))?.trim() || undefined
+  }
+
+  function parseKeys(source: string | undefined): Record<string, true> {
+    const keys: Record<string, true> = {}
+    for (const line of (source ?? '').split(/\r?\n/)) {
+      const entry = envEntryAt(line)
+      if (entry && !entry.key.startsWith('DOTENV_PUBLIC_KEY'))
+        keys[entry.key] = true
+    }
+    return keys
+  }
+
+  async function getValue(): Promise<void> {
+    const root = projectRoot()
+    if (!root)
+      return
+    const file = targetFile(root)
+    const key = await askKey(root, file, 'Get an env value')
+    if (!key)
+      return
+    const value = await buddy(root, ['env:get', key, '--file', file])
+    if (value === undefined)
+      return
+    const choice = await api.window.showInformationMessage(`${key} is set in ${file}.`, 'Copy Value')
+    if (choice === 'Copy Value')
+      await api.env.clipboard.writeText(value.replace(/\r?\n$/, ''))
+  }
+
+  async function setValue(): Promise<void> {
+    const root = projectRoot()
+    if (!root)
+      return
+    const file = targetFile(root)
+    const key = (await api.window.showInputBox({ title: `Set an env value (${file})`, prompt: 'Key', validateInput: value => /^[A-Z_a-z][\w.-]*$/.test(value.trim()) ? undefined : 'Letters, digits and underscores, not starting with a digit' }))?.trim()
+    if (!key)
+      return
+    const value = await api.window.showInputBox({ title: `Set ${key} (${file})`, prompt: 'Value. It is encrypted when the file is.', password: true })
+    if (value === undefined)
+      return
+    if (await buddy(root, ['env:set', key, value, '--file', file]) !== undefined)
+      void api.window.showInformationMessage(`Stacks: set ${key} in ${file}.`)
+  }
+
+  async function wholeFile(command: 'env:encrypt' | 'env:decrypt' | 'env:rotate', warning?: string): Promise<void> {
+    const root = projectRoot()
+    if (!root)
+      return
+    const file = targetFile(root)
+    if (warning) {
+      const confirmed = await api.window.showWarningMessage(warning.replace('{file}', file), { modal: true }, 'Continue')
+      if (confirmed !== 'Continue')
+        return
+    }
+    if (await buddy(root, [command, '--file', file]) !== undefined)
+      void api.window.showInformationMessage(`Stacks: ./buddy ${command} finished for ${file}.`)
+  }
+
+  return {
+    activate(context) {
+      context.subscriptions.push(
+        diagnostics,
+        api.languages.registerHoverProvider([{ scheme: 'file', pattern: '**/.env*' }, { language: 'dotenv' }], hover),
+        api.workspace.onDidOpenTextDocument(checkMissingKeys),
+        api.workspace.onDidChangeTextDocument(event => checkMissingKeys(event.document)),
+        api.workspace.onDidSaveTextDocument(checkMissingKeys),
+        api.workspace.onDidCloseTextDocument(document => diagnostics.delete(document.uri)),
+        api.commands.registerCommand(ENV_COMMANDS.get, getValue),
+        api.commands.registerCommand(ENV_COMMANDS.set, setValue),
+        api.commands.registerCommand(ENV_COMMANDS.encrypt, () => wholeFile('env:encrypt')),
+        api.commands.registerCommand(ENV_COMMANDS.decrypt, () => wholeFile('env:decrypt', 'This writes every value in {file} to disk in plaintext. Encrypt it again before committing.')),
+        api.commands.registerCommand(ENV_COMMANDS.rotate, () => wholeFile('env:rotate', 'This generates a new keypair for {file} and re-encrypts every value with it. Deployments still holding the old private key will no longer decrypt it.')),
+      )
+
+      for (const document of api.workspace.textDocuments)
+        checkMissingKeys(document)
+    },
+  }
+}

package/ide/vscode/src/extension.ts

@@ -0,0 +1,153 @@
+/**
+ * The extension entry VS Code loads (`main` in package.json, bundled to
+ * dist/extension.js). It wires the real machine into the controllers and
+ * starts each part; the behavior lives in the modules it imports:
+ *
+ * - ./stacks.ts   preview, dev server and buddy commands
+ * - ./pickier.ts  lint diagnostics, formatting and fix-all from the project's pickier
+ * - ./env.ts      decrypted env values on hover, missing keys, `buddy env:*` commands
+ * - stx           the stx extension's language support, built in from `@stacksjs/stx-vscode`
+ *
+ * Nothing here depends on another extension being installed.
+ */
+import type { PickierProcess } from './pickier'
+import type { Host } from './stacks'
+import { execFile, spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { connect } from 'node:net'
+import { join } from 'node:path'
+import process from 'node:process'
+import { createInterface } from 'node:readline'
+import { activateStxLanguage, deactivateStxLanguage, STX_EXTENSION_ID } from '@stacksjs/stx-vscode'
+import * as vscode from 'vscode'
+import { createEnvSupport, projectDecryptor } from './env'
+import { createPickierSupport } from './pickier'
+import { createStacksExtension } from './stacks'
+
+const PROBE_TIMEOUT_MS = 500
+
+function read(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8')
+  }
+  catch {
+    return undefined
+  }
+}
+
+function exec(file: string, args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, {
+      cwd,
+      timeout: 60_000,
+      maxBuffer: 32 * 1024 * 1024,
+      env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },
+    }, (error, stdout) => error ? reject(error) : resolve(String(stdout)))
+  })
+}
+
+const envHost = { exists: existsSync, read, exec, environment: process.env }
+
+const host: Host = {
+  exists: path => existsSync(path),
+  read,
+  exec,
+
+  probe(hostname, port) {
+    return new Promise((resolve) => {
+      const socket = connect({ host: hostname, port })
+      const finish = (open: boolean) => {
+        socket.destroy()
+        resolve(open)
+      }
+
+      socket.setTimeout(PROBE_TIMEOUT_MS)
+      socket.once('connect', () => finish(true))
+      socket.once('timeout', () => finish(false))
+      socket.once('error', () => finish(false))
+    })
+  },
+
+  sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+
+  decryptEnv: root => projectDecryptor(envHost, root),
+}
+
+/**
+ * `bun --config=<empty> dist/pickier-worker.js` in the project root. The
+ * explicit config keeps the project's bunfig.toml out: its `preload` boots the
+ * framework (env decryption, auto-imports), which pickier does not need.
+ */
+function spawnBun(bun: string, script: string, cwd: string): PickierProcess {
+  const child = spawn(bun, [`--config=${join(script, '..', 'pickier-worker.bunfig.toml')}`, script], {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },
+  })
+  const lines = createInterface({ input: child.stdout })
+  let exited = false
+  const exitListeners: Array<() => void> = []
+  const exit = () => {
+    if (exited)
+      return
+    exited = true
+    for (const listener of exitListeners)
+      listener()
+  }
+  child.once('exit', exit)
+  child.once('error', exit)
+  child.stderr.resume()
+
+  return {
+    write: line => child.stdin.write(line),
+    onLine: listener => lines.on('line', listener),
+    onExit: listener => exitListeners.push(listener),
+    kill: () => child.kill(),
+  }
+}
+
+const stacks = createStacksExtension(vscode, host)
+const env = createEnvSupport(vscode, envHost)
+let pickier: ReturnType<typeof createPickierSupport> | undefined
+
+/**
+ * What `activate` resolves to. The stx extension (Stacks.vscode-stx) reads
+ * `stx.active` and stands down when it is true, so the two never register
+ * stx support twice in one window.
+ */
+export interface StacksExtensionApi {
+  stx: { active: boolean }
+}
+
+async function startStx(context: vscode.ExtensionContext): Promise<boolean> {
+  try {
+    await activateStxLanguage(context, {
+      assetsPath: join(context.extensionPath, 'dist', 'stx'),
+      // The stx extension contributes the snippets in its manifest; offering
+      // them here as well would show each one twice.
+      snippets: !vscode.extensions.getExtension(STX_EXTENSION_ID),
+    })
+    return true
+  }
+  catch (error) {
+    console.error('Stacks: stx support failed to start', error)
+    return false
+  }
+}
+
+export async function activate(context: vscode.ExtensionContext): Promise<StacksExtensionApi> {
+  stacks.activate(context)
+  env.activate(context)
+  pickier = createPickierSupport(vscode, { exists: existsSync, spawnBun }, {
+    workerPath: join(context.extensionPath, 'dist', 'pickier-worker.js'),
+  })
+  pickier.activate(context)
+
+  return { stx: { active: await startStx(context) } }
+}
+
+export function deactivate(): void {
+  stacks.deactivate()
+  pickier?.deactivate()
+  deactivateStxLanguage()
+}

package/ide/vscode/src/pickier-protocol.ts

@@ -0,0 +1,51 @@
+/**
+ * The line protocol between the extension and dist/pickier-worker.js.
+ *
+ * Pickier runs on Bun (its config is a TypeScript file, and it uses Bun's glob
+ * and YAML APIs), and VS Code runs extensions on Node, so the extension keeps
+ * one Bun process per project and talks to it over stdin/stdout: one JSON
+ * object per line each way, answers matched to requests by `id`.
+ */
+
+export type PickierOperation = 'lint' | 'fix' | 'format'
+
+export interface PickierRequest {
+  id: number
+  op: PickierOperation
+  /** Absolute path, for config ignores and the per-extension rules. */
+  file: string
+  text: string
+}
+
+/** One issue, as pickier's `lintText` reports it: 1-based line and column. */
+export interface PickierIssue {
+  line: number
+  column: number
+  ruleId: string
+  message: string
+  severity: 'error' | 'warning'
+  help?: string
+}
+
+export type PickierResult =
+  | { op: 'lint', issues: PickierIssue[] }
+  /** `text` is null when the project's pickier predates `fixText`, or the file is ignored. */
+  | { op: 'fix' | 'format', text: string | null }
+
+export type PickierResponse =
+  | { id: number, ok: true, result: PickierResult }
+  | { id: number, ok: false, error: string, missing?: boolean }
+
+/** The first line the worker writes, once it has loaded the project's pickier and config. */
+export interface PickierReady {
+  ready: true
+  version: string
+  fixText: boolean
+}
+
+/** What the worker writes instead when the project has no pickier it can load. */
+export interface PickierUnavailable {
+  ready: false
+  error: string
+  missing: boolean
+}