@stacksjs/actions 0.70.88 → 0.70.91

package/dist/templates.js

@@ -0,0 +1,301 @@
+export const CODE_TEMPLATES = {
+  action: `import { Action } from '@stacksjs/actions'
+
+export default new Action({
+  name: '{0}',
+  description: '{0} action',
+
+  handle() {
+    return 'Hello World action'
+  },
+})`,
+  actionWithValidation: `import { Action } from '@stacksjs/actions'
+import { schema, validate } from '@stacksjs/validation'
+
+export default new Action({
+  name: '{0}',
+  description: '{0} action',
+
+  async handle(request) {
+    // Replace these rules with whatever this action expects. The
+    // returned object is typed to the rule shape; type-narrow further
+    // by passing a generic to validate<Payload>().
+    const data = await validate(request, {
+      // example: title: schema.string().required().min(1),
+    })
+
+    return { ok: true, data }
+  },
+})`,
+  actionWithAuth: `import { Action } from '@stacksjs/actions'
+
+export default new Action({
+  name: '{0}',
+  description: '{0} action (authenticated)',
+
+  async handle(request) {
+    const user = await request.user()
+    if (!user) {
+      return new Response('Unauthorized', { status: 401 })
+    }
+
+    return { ok: true, userId: user.id }
+  },
+})`,
+  actionWithBoth: `import { Action } from '@stacksjs/actions'
+import { schema, validate } from '@stacksjs/validation'
+
+export default new Action({
+  name: '{0}',
+  description: '{0} action (authenticated + validated)',
+
+  async handle(request) {
+    const user = await request.user()
+    if (!user) {
+      return new Response('Unauthorized', { status: 401 })
+    }
+
+    const data = await validate(request, {
+      // example: title: schema.string().required().min(1),
+    })
+
+    return { ok: true, userId: user.id, data }
+  },
+})`,
+  component: `<script setup lang="ts">
+console.log('Hello World component created')
+</script>
+
+<template>
+  <div>
+    Some HTML block
+  </div>
+</template>`,
+  page: `<script setup lang="ts">
+console.log('Hello World page created')
+</script>
+
+<template>
+  <div>
+    Visit http://127.0.0.1/{0}
+  </div>
+</template>`,
+  function: `// reactive state
+const {0} = ref(0)
+
+// functions that mutate state and trigger updates
+function increment() {
+  {0}.value++
+}
+
+export {
+  {0},
+  increment,
+}`,
+  language: `button:
+  text: Copy`,
+  notification: `import type { {0} } from '@stacksjs/types'
+
+function content(): string {
+  return 'example'
+}
+
+function send(): {0} {
+  return {
+    content: content(),
+  }
+}`,
+  mail: `import { Mailable } from '@stacksjs/email'
+
+/**
+ * Props passed into the {0} email. Add the fields your template
+ * needs and they'll flow through to the stx template's \`props\` \u2014
+ * \`Mailable<{0}Props>\` ensures \`.template()\` and \`this.props\`
+ * type-check against this shape (stacksjs/stacks#1903).
+ */
+export interface {0}Props extends Record<string, unknown> {
+  /** Recipient email address. */
+  to: string
+  /** Display name for the greeting (falls back to 'there'). */
+  userName?: string
+}
+
+/**
+ * {0} mailable. Subclass of \`Mailable<{0}Props>\` \u2014 \`build()\` wires the
+ * recipient / subject / template (props typed against \`{0}Props\`),
+ * then \`send()\` (inherited) dispatches via the configured mail driver.
+ *
+ * @example
+ * \`\`\`ts
+ * await new {0}({ to: 'user@example.com', userName: 'Ada' }).send()
+ * \`\`\`
+ */
+export class {0} extends Mailable<{0}Props> {
+  constructor(private readonly props: {0}Props) {
+    super()
+  }
+
+  build(): this {
+    return this
+      .to(this.props.to)
+      .subject('{0}')
+      .template('{1}', {
+        to: this.props.to,
+        userName: this.props.userName ?? 'there',
+      })
+  }
+}`,
+  mailTemplate: `<script server>
+// Generated by \`buddy make:mail {0}\`. Edit freely \u2014 \`props\` is the
+// object passed by the Mailable's \`build()\`.
+const appName = props.appName || 'Stacks'
+const appUrl = props.appUrl || 'https://stacksjs.com'
+const userName = props.userName || 'there'
+const primaryColor = props.primaryColor || '#3451b2'
+const primaryColorDark = props.primaryColorDark || '#2a4198'
+const subject = props.subject || '{0}'
+const year = props.year || new Date().getFullYear()
+</script>
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <title>{{ subject }}</title>
+  <style>
+    .button { display: inline-block; padding: 14px 32px; background-color: {{ primaryColor }}; color: #ffffff !important; text-decoration: none; border-radius: 6px; font-weight: 600; font-size: 16px; text-align: center; }
+    .button:hover { background-color: {{ primaryColorDark }}; }
+    @media only screen and (max-width: 600px) {
+      .container { width: 100% !important; padding: 20px !important; }
+      .content { padding: 24px !important; }
+      .button { display: block !important; width: 100% !important; }
+    }
+  </style>
+</head>
+<body style="margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: #f4f4f5; line-height: 1.6;">
+  <table role="presentation" cellpadding="0" cellspacing="0" style="width: 100%; border-collapse: collapse;">
+    <tr>
+      <td style="padding: 40px 20px;">
+        <table role="presentation" cellpadding="0" cellspacing="0" class="container" style="max-width: 600px; margin: 0 auto; background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);">
+          <tr>
+            <td style="background-color: {{ primaryColor }}; padding: 30px 40px; text-align: center;">
+              <h1 style="margin: 0; color: #ffffff; font-size: 24px; font-weight: 600;">{{ appName }}</h1>
+            </td>
+          </tr>
+          <tr>
+            <td class="content" style="padding: 40px;">
+              <h2 style="margin: 0 0 20px; color: #111827; font-size: 20px; font-weight: 600;">{0}</h2>
+              <p style="margin: 0 0 20px; color: #4b5563; font-size: 16px;">Hi {{ userName }},</p>
+              <p style="margin: 0 0 20px; color: #4b5563; font-size: 16px;">Your message body goes here.</p>
+              <table role="presentation" cellpadding="0" cellspacing="0" style="margin: 30px 0;">
+                <tr><td><a href="{{ appUrl }}" class="button">Open {{ appName }}</a></td></tr>
+              </table>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 40px; background-color: #f9fafb; border-top: 1px solid #e5e7eb;">
+              <p style="margin: 0; color: #6b7280; font-size: 12px; text-align: center;">This is an automated message from {{ appName }}.</p>
+              <p style="margin: 10px 0 0; color: #9ca3af; font-size: 11px; text-align: center;">&copy; {{ year }} {{ appName }}. All rights reserved.</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>`,
+  middleware: `import type { Request } from '@stacksjs/router'
+import { Middleware } from '@stacksjs/router'
+
+export default new Middleware({
+  name: '{0}',
+  priority: 1,
+  async handle(request: Request) {
+    // Your middleware logic here
+  },
+})`,
+  model: `import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+export default defineModel({
+  name: '{0}',
+  table: '{1}',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  traits: {
+    useTimestamps: true,
+
+    useSeeder: {
+      count: 10,
+    },
+  },
+
+  attributes: {
+    // your attributes here
+  },
+} as const)`,
+  migration: `import type { Database } from '@stacksjs/database'
+
+export async function up(db: Database): Promise<void> {
+  await db.schema
+    .createTable('{0}')
+    .addColumn('id', 'integer', col => col.autoIncrement().primaryKey())
+    .execute()
+}`,
+  stackPackageJson: `{
+  "name": "{0}",
+  "version": "0.0.1",
+  "type": "module",
+  "stacks": {
+    "name": "{1}",
+    "description": "A Stacks extension"
+  }
+}`,
+  job: `import { Job } from '@stacksjs/jobs'
+
+export default new Job({
+  name: '{0}',
+  description: '{0} job',
+
+  async handle() {
+    // Your job logic here
+    console.log('Job executed')
+  },
+})`,
+  event: `import { Event } from '@stacksjs/events'
+
+export default new Event({
+  name: '{0}',
+  description: '{0} event',
+
+  async handle(data: any) {
+    // Your event handler logic here
+    console.log('Event handled:', data)
+  },
+})`,
+  listener: `import { Listener } from '@stacksjs/events'
+
+export default new Listener({
+  name: '{0}',
+  description: '{0} listener',
+
+  async handle(data: any) {
+    // Your listener logic here
+    console.log('Listener triggered:', data)
+  },
+})`,
+  command: `import { Command } from '@stacksjs/cli'
+
+export default new Command({
+  name: '{0}',
+  description: '{0} command',
+
+  async handle() {
+    // Your command logic here
+    console.log('Command executed')
+  },
+})`
+};

package/dist/test/feature.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/feature.js

@@ -0,0 +1,11 @@
+import process from "node:process";
+import { log } from "@stacksjs/cli";
+import { projectPath } from "@stacksjs/path";
+const proc = Bun.spawn(["sh", "-c", "bun test ./tests/feature/**"], {
+  cwd: projectPath(),
+  stdio: ["inherit", "inherit", "inherit"]
+}), exitCode = await proc.exited;
+if (exitCode !== 0) {
+  log.error("Tests failed");
+  process.exit(exitCode ?? 1);
+}

package/dist/test/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/index.js

@@ -0,0 +1,11 @@
+import process from "node:process";
+import { log } from "@stacksjs/cli";
+import { projectPath } from "@stacksjs/path";
+const proc = Bun.spawn(["sh", "-c", "bun test --timeout 30000 ./tests/feature/** ./tests/integration/** ./tests/unit/**"], {
+  cwd: projectPath(),
+  stdio: ["inherit", "inherit", "inherit"]
+}), exitCode = await proc.exited;
+if (exitCode !== 0) {
+  log.error("Tests failed");
+  process.exit(exitCode ?? 1);
+}

package/dist/test/ui.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/ui.js

@@ -0,0 +1,4 @@
+import { runCommand } from "@stacksjs/cli";
+import { NpmScript } from "@stacksjs/enums";
+import { frameworkPath } from "@stacksjs/path";
+await runCommand(NpmScript.TestUi, { verbose: !0, cwd: frameworkPath() });

package/dist/test/unit.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/unit.js

@@ -0,0 +1,11 @@
+import process from "node:process";
+import { log } from "@stacksjs/cli";
+import { projectPath } from "@stacksjs/path";
+const proc = Bun.spawn(["sh", "-c", "bun test ./tests/unit/**"], {
+  cwd: projectPath(),
+  stdio: ["inherit", "inherit", "inherit"]
+}), exitCode = await proc.exited;
+if (exitCode !== 0) {
+  log.error("Tests failed");
+  process.exit(exitCode ?? 1);
+}

package/dist/typecheck.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/typecheck.js

@@ -0,0 +1,4 @@
+import { runCommands } from "@stacksjs/cli";
+import { NpmScript } from "@stacksjs/enums";
+import { projectPath } from "@stacksjs/path";
+await runCommands([NpmScript.TestTypes], { cwd: projectPath() });

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+import type { TypesOptions } from '@stacksjs/types';
+export declare function invoke(options?: TypesOptions): Promise<void>;
+export declare function types(options: TypesOptions): Promise<void>;

package/dist/types.js

@@ -0,0 +1,16 @@
+import process from "node:process";
+import { NpmScript } from "@stacksjs/enums";
+import { log } from "@stacksjs/logging";
+import { ExitCode } from "@stacksjs/types";
+import { runNpmScript } from "@stacksjs/utils";
+export async function invoke(options) {
+  const results = await runNpmScript(NpmScript.TypesFix, options);
+  if (results.isErr) {
+    log.error("There was an error fixing your types.", results.error);
+    process.exit(ExitCode.FatalError);
+  }
+  log.success("Types are set");
+}
+export async function types(options) {
+  return await invoke(options);
+}

package/dist/upgrade/binary.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/upgrade/binary.js

@@ -0,0 +1,29 @@
+import process from "node:process";
+import { runCommand } from "@stacksjs/cli";
+import { log } from "@stacksjs/logging";
+import { path } from "@stacksjs/path";
+import { ExitCode } from "@stacksjs/types";
+import { fs, storage } from "@stacksjs/storage";
+const source = path.buddyPath("dist/stacks"), destination = path.homeDir(".stacks/bin/stacks"), destinationDir = path.homeDir(".stacks/bin/");
+log.info("Upgrading `stacks`...");
+const result = await runCommand("bun compile.ts", { cwd: path.buddyPath() });
+if (result.isErr) {
+  log.error("There was an error compiling the binary", result.error);
+  process.exit(ExitCode.FatalError);
+}
+if (await storage.exists(source))
+  try {
+    log.info("Updating Binary...");
+    log.info(`Source: ${source}`);
+    log.info(`Destination: ${destination}`);
+    await fs.ensureDir(destinationDir);
+    await fs.move(source, destination, { overwrite: !0 });
+    log.success("Binary Latest Version Is Used");
+  } catch (err) {
+    log.error(err);
+    process.exit(ExitCode.FatalError);
+  }
+else {
+  log.error(`Binary source not found: ${source}`);
+  process.exit(ExitCode.FatalError);
+}

package/dist/upgrade/bun.d.ts

@@ -0,0 +1 @@
+

package/dist/upgrade/dependencies.d.ts

@@ -0,0 +1 @@
+

package/dist/upgrade/framework-utils.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Resolve the target channel and git ref from CLI options and persisted channel.
+ * Priority: --version > --canary > --stable > persisted channel
+ *
+ * Branch model: `main` is the bleeding-edge "dump everything" branch; `stable`
+ * is the vetted branch that PRs are merged into from `main` once main is proven.
+ * So the `stable` channel tracks the `stable` branch (vetted) and the `canary`
+ * channel tracks the `main` branch (bleeding edge). A pinned `--version` still
+ * resolves to the matching `vX` tag.
+ */
+export declare function resolveUpgradeContext(options: {
+  version?: string
+  canary?: boolean
+  stable?: boolean
+}, currentChannel: 'stable' | 'canary'): UpgradeContext;
+/**
+ * Build the gitit template string for a path under the stacks repo.
+ * `subPath` is relative to the repo root (e.g. `storage/framework/core`).
+ */
+export declare function buildTemplateString(ref: string, subPath?: string): string;
+/**
+ * Read a version from a package.json file. Returns null on any error.
+ */
+export declare function readVersion(pkgPath: string): string | null;
+/**
+ * Read the persisted channel from the channel file.
+ */
+export declare function readChannel(channelFilePath: string): 'stable' | 'canary';
+/**
+ * Persist the channel to the channel file.
+ */
+export declare function writeChannel(channelFilePath: string, ch: 'stable' | 'canary'): void;
+/**
+ * Read the last-synced `{ channel, sha }` from `.stacks-version`.
+ *
+ * Returns null on absence or any malformed content — callers treat null as
+ * "no prior sync", which always falls through to a sync (first-run safe). The
+ * stored format is a single line: `"<channel> <40-hex-sha>"`. A bare sha
+ * (legacy) or unknown channel parses to null so it never wrongly short-circuits.
+ */
+export declare function readSyncedVersion(versionFilePath: string): SyncedVersion | null;
+/**
+ * Persist the last-synced channel + sha to `.stacks-version`.
+ */
+export declare function writeSyncedVersion(versionFilePath: string, ch: 'stable' | 'canary', sha: string): void;
+/**
+ * Pure decision for the "already up to date" short-circuit. Returns true only
+ * when a sync can be safely skipped: no override flags, not a pinned version,
+ * a resolved remote sha, a prior sync on the SAME channel, and the synced sha
+ * equals the remote sha. Any of:
+ *   - `force` (explicit re-sync)
+ *   - `targetVersion` (pinned tag — always install)
+ *   - `remoteSha === null` (network/git failure → fail open to sync)
+ *   - `synced === null` (first run → always sync)
+ *   - channel mismatch (channel switch never short-circuits)
+ *   - sha mismatch (a newer commit is available)
+ * yields false (proceed with the sync).
+ */
+export declare function shouldShortCircuit(args: {
+  force: boolean
+  targetVersion?: string
+  remoteSha: string | null
+  synced: SyncedVersion | null
+  channel: 'stable' | 'canary'
+}): boolean;
+/**
+ * Determine the user-facing log message for the upgrade action.
+ */
+export declare function resolveUpgradeMessage(ctx: UpgradeContext, currentChannel: 'stable' | 'canary', isStableFlag: boolean): string;
+/**
+ * Determine the user-facing success message after an upgrade.
+ */
+export declare function resolveSuccessMessage(ctx: UpgradeContext, currentVersion: string | null, newVersion: string | null, currentChannel: 'stable' | 'canary', force: boolean): string;
+/**
+ * Auto-detect a local stacks checkout the user might be developing against.
+ *
+ * Order:
+ *   1. `STACKS_LOCAL_PATH` env var (explicit)
+ *   2. Sibling directory: `<project>/../stacks`
+ *   3. `~/Code/stacks` and a few common dev paths
+ *
+ * Returns null if nothing looks like a stacks checkout. We confirm by checking
+ * for `storage/framework/core/buddy/package.json` — the canonical marker.
+ */
+export declare function detectLocalStacks(projectRoot: string): string | null;
+/**
+ * Walk a directory recursively and return a Map of relative-path → entry,
+ * with each entry's size + content hash captured at the time of the call.
+ * Hashing the entire tree at snapshot time (rather than at diff time) means
+ * the "before" snapshot stays valid even after `cpSync` overwrites the
+ * files in place.
+ *
+ * Async because we read each file via `Bun.file().arrayBuffer()`. On a
+ * 3000-file framework tree this completes in ~50ms — `Bun.hash` is xxh3,
+ * not a crypto hash, and the I/O is fully parallelized.
+ */
+export declare function snapshotTree(root: string, skip?: string[]): Promise<Map<string, SnapshotEntry>>;
+/**
+ * Diff two snapshots produced by `snapshotTree`. Pure comparison — both
+ * inputs already carry their content hash, so this is just bookkeeping.
+ */
+export declare function diffSnapshots(before: Map<string, SnapshotEntry>, after: Map<string, SnapshotEntry>): ChangeSummary;
+export declare const MANAGED_PATHS: ManagedPath[];
+export declare interface UpgradeContext {
+  channel: 'stable' | 'canary'
+  ref: string
+  targetVersion?: string
+}
+/**
+ * The last-synced channel + commit sha, persisted to `.stacks-version` so
+ * `buddy update` can short-circuit when the project is already on the latest
+ * commit of its channel.
+ */
+export declare interface SyncedVersion {
+  channel: 'stable' | 'canary'
+  sha: string
+}
+/**
+ * Framework-managed paths, relative to the project root, that `buddy update`
+ * keeps in sync with the upstream stacks repo. Each entry can be a directory
+ * (synced recursively) or a single file. The `subPath` is the path inside the
+ * upstream stacks checkout — almost always the same as `localPath`, except
+ * for root scripts that live at the project root in apps but at the repo root
+ * in the stacks monorepo.
+ */
+export declare interface ManagedPath {
+  localPath: string
+  subPath: string
+  isFile?: boolean
+  skip?: string[]
+  label: string
+}
+/**
+ * Snapshot entry. We capture size + content hash at snapshot time so the
+ * before/after diff can detect "actually changed" vs "just re-copied with
+ * fresh mtimes". `cpSync` and `downloadTemplate` always touch mtimes,
+ * even when the destination bytes are identical to the source — using
+ * mtime as the change signal turns every no-op upgrade into a "1600
+ * changed" report.
+ */
+export declare interface SnapshotEntry {
+  size: number
+  hash: bigint
+}
+export declare interface ChangeSummary {
+  added: number
+  changed: number
+  removed: number
+  unchanged: number
+}