stacks 0.37.4 → 0.37.5

package/README.md

@@ -1,10 +1,15 @@
 # Rapid Application Development
 
-This Stacks.js framework/package contains the core logic—its runtime, helpers, and CLI (excluding the IDE setup).
+Develop modern framework-agnostic web apps & libraries, faster. Stacks.js is a progressive full-stack framework with an approachable & easy-to-use onboarding experience.
 
 ## ☘️ Features
 
-The ultimate goal of the framework is to _help you_ build applications rapidly. Whether it's APIs, a component and/or function library, or simply a statically generate site. Stacks is a toolkit of composables, methods, and other goodies required to build optimized outputs. It's a highly optimized build process that automatically generates `.mjs` & `.cjs` library distributions for you, including its TypeScript types.
+The goal of the framework is to _help you_ build applications rapidly & more efficiently, removing the boilerplate wherever possible—and the learning curve! Whether it's APIs, a component and/or function library, or simply a statically generate site, Stacks is a toolkit of composables, methods, and other goodies, required to build optimized outputs.
+
+In other words, it's a highly optimized build process that automatically generates:
+
+- `.mjs` & `.cjs` library distributions, including its TypeScript types
+- a highly-performant JavaScript production-ready server to be deployed anywhere (e.g. Netlify, Vercel, AWS, etc.)
 
 Other included core features are:
 

package/dist/cli/actions/build.d.ts

@@ -0,0 +1,7 @@
+export declare function buildComponentLibraries(): Promise<void>;
+export declare function buildVueComponentLibrary(): Promise<void>;
+export declare function buildWebComponentLibrary(): Promise<void>;
+export declare function buildDocs(): Promise<void>;
+export declare function buildStacks(): Promise<void>;
+export declare function buildFunctionsLibrary(): Promise<void>;
+export declare function startBuildProcess(options: any): Promise<void>;

package/dist/cli/actions/build.mjs

@@ -0,0 +1,117 @@
+import Prompts from "prompts";
+import consola from "consola";
+import { hasComponents, hasFunctions } from "@stacksjs/fs";
+import { runNpmScript } from "@stacksjs/helpers";
+import { ExitCode, NpmScript } from "@stacksjs/types";
+import { generateTypes } from "./types.mjs";
+const { prompts } = Prompts;
+export async function buildComponentLibraries() {
+  try {
+    await runNpmScript(NpmScript.GenerateEntries);
+    await buildVueComponentLibrary();
+    await buildWebComponentLibrary();
+  } catch (error) {
+    consola.error("There was an error building your component libraries.");
+    consola.error(error);
+  }
+}
+export async function buildVueComponentLibrary() {
+  consola.info("Building your component library...");
+  if (hasComponents()) {
+    try {
+      await runNpmScript(NpmScript.BuildComponents);
+      consola.success("Your component library was built successfully.");
+    } catch (error) {
+      consola.error("There was an error building your component library.");
+      consola.error(error);
+    }
+  } else {
+    consola.info("No components found.");
+  }
+}
+export async function buildWebComponentLibrary() {
+  consola.info("Building your component library for production use & npm/CDN distribution...");
+  if (hasComponents()) {
+    try {
+      await runNpmScript(NpmScript.BuildWebComponents);
+      consola.success("Your Web Component library was built successfully.");
+    } catch (error) {
+      consola.error("There was an error building your Web Component library.");
+      consola.error(error);
+    }
+  } else {
+    consola.info("No components found.");
+  }
+}
+export async function buildDocs() {
+  consola.info("Building the Artisan CLI...");
+  try {
+    await runNpmScript(NpmScript.BuildDocs);
+    consola.success("Artisan CLI was built successfully.");
+  } catch (error) {
+    consola.error("There was an error building the Artisan CLI.");
+    consola.error(error);
+  }
+}
+export async function buildStacks() {
+  consola.info("Building the Stacks Framework...");
+  try {
+    await runNpmScript(NpmScript.BuildStacks);
+    consola.success("Stacks was built successfully.");
+  } catch (error) {
+    consola.error("There was an error building the Stacks framework.");
+    consola.error(error);
+  }
+}
+export async function buildFunctionsLibrary() {
+  consola.info("Building your functions library for production use & npm/CDN distribution...");
+  if (hasFunctions()) {
+    try {
+      await runNpmScript(NpmScript.BuildFunctions);
+      consola.success("Your functions library was built successfully.");
+    } catch (error) {
+      consola.error("There was an error building your functions library.");
+      consola.error(error);
+    }
+  } else {
+    consola.info("No functions found.");
+  }
+}
+export async function startBuildProcess(options) {
+  if (options.components || options === "components") {
+    await buildComponentLibraries();
+  } else if (options.webComponents || options.elements || options === "web-components" || options === "elements") {
+    await buildWebComponentLibrary();
+  } else if (options.functions || options === "functions") {
+    await buildFunctionsLibrary();
+  } else if (options.docs || options === "docs") {
+    await buildDocs();
+  } else if (options.stacks || options === "stacks") {
+    await buildStacks();
+  } else if (options.npm || options === "npm") {
+    await buildComponentLibraries();
+    await buildFunctionsLibrary();
+    consola.success("All your libraries and its types were built successfully to be distributed on npm.");
+  } else {
+    const answer = await prompts.select({
+      type: "select",
+      name: "build",
+      message: "Which stack are you trying to build for production use?",
+      choices: [
+        { title: "Components", value: "components" },
+        { title: "Functions", value: "functions" },
+        { title: "Docs", value: "docs" }
+      ],
+      initial: 0
+    });
+    if (answer === "components")
+      await buildComponentLibraries();
+    if (answer === "functions")
+      await buildFunctionsLibrary();
+    else if (answer === "docs")
+      await buildDocs();
+    else
+      process.exit(ExitCode.InvalidArgument);
+  }
+  await generateTypes();
+}

package/dist/cli/actions/commit.d.ts

@@ -0,0 +1 @@
+export declare function commit(): Promise<void>;

package/dist/cli/actions/commit.mjs

@@ -0,0 +1,8 @@
+import consola from "consola";
+import { runNpmScript } from "@stacksjs/helpers";
+import { NpmScript } from "@stacksjs/types";
+export async function commit() {
+  consola.info("Committing...");
+  await runNpmScript(NpmScript.Commit);
+  consola.success("Committed.");
+}

package/dist/cli/actions/dev.d.ts

@@ -0,0 +1 @@
+export declare function startDevelopmentServer(options: any): Promise<void>;

package/dist/cli/actions/dev.mjs

@@ -0,0 +1,34 @@
+import Prompts from "prompts";
+import consola from "consola";
+import { runNpmScript } from "@stacksjs/helpers";
+import { ExitCode, NpmScript } from "@stacksjs/types";
+const { prompts } = Prompts;
+export async function startDevelopmentServer(options) {
+  if (options.components || options === "components") {
+    consola.info("Starting development server for your components...");
+    await runNpmScript(NpmScript.DevComponents);
+  } else if (options.docs || options === "docs") {
+    consola.info("Starting development server for your documentation...");
+    await runNpmScript(NpmScript.DevDocs);
+  } else {
+    const answer = await prompts.select({
+      type: "select",
+      name: "development",
+      message: "Which development server are you trying to start?",
+      choices: [
+        { title: "Components", value: "components" },
+        { title: "Docs", value: "docs" }
+      ],
+      initial: 0
+    });
+    if (answer === "components") {
+      consola.info("Starting development server for your components...");
+      await runNpmScript(NpmScript.DevComponents);
+    } else if (answer === "docs") {
+      consola.info("Starting docs server for your components...");
+      await runNpmScript(NpmScript.DevDocs);
+    } else {
+      process.exit(ExitCode.InvalidArgument);
+    }
+  }
+}

package/dist/cli/actions/examples.d.ts

@@ -0,0 +1,3 @@
+export declare function testComponentExample(): Promise<void>;
+export declare function testWebComponentExample(): Promise<void>;
+export declare function runExample(options: any): Promise<void>;

package/dist/cli/actions/examples.mjs

@@ -0,0 +1,57 @@
+import Prompts from "prompts";
+import consola from "consola";
+import { hasComponents } from "@stacksjs/fs";
+import { runNpmScript } from "@stacksjs/helpers";
+import { ExitCode, NpmScript } from "@stacksjs/types";
+const { prompts } = Prompts;
+export async function testComponentExample() {
+  if (hasComponents()) {
+    try {
+      await runNpmScript(NpmScript.ExampleVue);
+      consola.success("Your component library was built successfully.");
+    } catch (error) {
+      consola.error("There was an error building your component library.");
+      consola.error(error);
+    }
+  } else {
+    consola.info("No components found.");
+  }
+}
+export async function testWebComponentExample() {
+  consola.info("Building your Web Component library...");
+  if (hasComponents()) {
+    try {
+      await runNpmScript(NpmScript.BuildWebComponents);
+      consola.success("Your Web Component library was built successfully.");
+    } catch (error) {
+      consola.error("There was an error building your Web Component library.");
+      consola.error(error);
+    }
+  } else {
+    consola.info("No components found.");
+  }
+}
+export async function runExample(options) {
+  if (options.components || options === "components" || options === "vue") {
+    await testComponentExample();
+  } else if (options.webComponents || options.elements || options === "web-components" || options === "elements") {
+    await testWebComponentExample();
+  } else {
+    const answer = await prompts.select({
+      type: "select",
+      name: "example",
+      message: "Which example are you trying to view?",
+      choices: [
+        { title: "Components", value: "components" },
+        { title: "Web Components", value: "web-components" }
+      ],
+      initial: 0
+    });
+    if (answer === "components")
+      await testComponentExample();
+    if (answer === "web-components")
+      await testWebComponentExample();
+    else
+      process.exit(ExitCode.InvalidArgument);
+  }
+}

package/dist/cli/actions/fresh.d.ts

@@ -0,0 +1 @@
+export declare function reinstallNpmDependencies(): Promise<void>;

package/dist/cli/actions/fresh.mjs

@@ -0,0 +1,8 @@
+import consola from "consola";
+import { runNpmScript } from "@stacksjs/helpers";
+import { NpmScript } from "@stacksjs/types";
+export async function reinstallNpmDependencies() {
+  consola.info("Reinstalling your npm dependencies...");
+  await runNpmScript(NpmScript.Fresh);
+  consola.success("Successfully reinstalled your npm dependencies.");
+}

package/dist/cli/actions/generate.d.ts

@@ -0,0 +1,7 @@
+export declare function generateLibEntries(): Promise<void>;
+export declare function generateVueCompat(): Promise<void>;
+export declare function generateWebTypes(): Promise<void>;
+export declare function generateVsCodeCustomData(): Promise<void>;
+export declare function generateIdeHelpers(): Promise<void>;
+export declare function generateComponentMeta(): Promise<void>;
+export declare function startGenerationProcess(options: any): Promise<void>;

package/dist/cli/actions/generate.mjs

@@ -0,0 +1,117 @@
+import consola from "consola";
+import Prompts from "prompts";
+import { runNpmScript } from "@stacksjs/helpers";
+import { ExitCode, NpmScript } from "@stacksjs/types";
+import { lintFix } from "./lint.mjs";
+import { generateTypes } from "./types.mjs";
+const { prompts } = Prompts;
+export async function generateLibEntries() {
+  try {
+    await runNpmScript(NpmScript.GenerateEntries, "ignore");
+    consola.success("Library entry points were generated successfully.");
+  } catch (error) {
+    consola.error("There was an error generating your library entry points.");
+    consola.error(error);
+  }
+}
+export async function generateVueCompat() {
+  try {
+    await runNpmScript(NpmScript.GenerateVueCompat, "ignore");
+    consola.success("Vue 2 & 3 compatibility was generated successfully.");
+  } catch (error) {
+    consola.error("There was an error generating Vue compatibility.");
+    consola.error(error);
+  }
+}
+export async function generateWebTypes() {
+  try {
+    await runNpmScript(NpmScript.GenerateWebTypes, "ignore");
+    consola.success("Successfully generated the web-types.json file.");
+  } catch (error) {
+    consola.error("There was an error generating the web-types.json file");
+    consola.error(error);
+    process.exit(ExitCode.FatalError);
+  }
+}
+export async function generateVsCodeCustomData() {
+  try {
+    await runNpmScript(NpmScript.GenerateVsCodeCustomData, "ignore");
+    await lintFix("ignore");
+    consola.success("Successfully generated the custom-elements.json file.");
+  } catch (error) {
+    consola.error("There was an error generating the custom-elements.json file");
+    consola.error(error);
+    process.exit(ExitCode.FatalError);
+  }
+}
+export async function generateIdeHelpers() {
+  try {
+    await runNpmScript(NpmScript.GenerateIdeHelpers, "ignore");
+    await lintFix("ignore");
+    consola.success("Successfully generated IDE helpers.");
+  } catch (error) {
+    consola.error("There was an error generating IDE helpers.");
+    consola.error(error);
+    process.exit(ExitCode.FatalError);
+  }
+}
+export async function generateComponentMeta() {
+  try {
+    await runNpmScript(NpmScript.GenerateComponentMeta, "ignore");
+    await lintFix("ignore");
+    consola.success("Successfully generated component meta.");
+  } catch (error) {
+    consola.error("There was an error generating your component meta information.");
+    consola.error(error);
+    process.exit(ExitCode.FatalError);
+  }
+}
+export async function startGenerationProcess(options) {
+  if (options.types || options === "types") {
+    await generateTypes();
+  } else if (options.entries || options === "entries") {
+    await generateLibEntries();
+  } else if (options.webTypes || options === "web-types") {
+    await generateWebTypes();
+  } else if (options.customData || options === "custom-data") {
+    await generateVsCodeCustomData();
+  } else if (options.ideHelpers || options === "ide-helpers") {
+    await generateIdeHelpers();
+  } else if (options.vueCompatibility || options === "vue-compatibility") {
+    await generateVueCompat();
+  } else if (options.componentMeta || options === "component-meta") {
+    await generateComponentMeta();
+  } else {
+    const answer = await prompts.select({
+      type: "select",
+      name: "generate",
+      message: "What are you trying to generate?",
+      choices: [
+        { title: "1.) TypeScript Types", value: "types" },
+        { title: "2.) Library Entry Points", value: "entries" },
+        { title: "3.) Web Types", value: "web-types" },
+        { title: "4.) VS Code Custom Data", value: "custom-data" },
+        { title: "5.) IDE Helpers", value: "ide-helpers" },
+        { title: "6.) Vue 2 & 3 Compatibility", value: "vue-compatibility" },
+        { title: "7.) Component Meta", value: "component-meta" }
+      ],
+      initial: 0
+    });
+    if (answer === "types")
+      await generateTypes();
+    else if (answer === "entries")
+      await generateLibEntries();
+    else if (answer === "web-types")
+      await generateWebTypes();
+    else if (answer === "custom-data")
+      await generateVsCodeCustomData();
+    else if (answer === "ide-helpers")
+      await generateIdeHelpers();
+    else if (answer === "vue-compatibility")
+      await generateVueCompat();
+    else if (answer === "component-meta")
+      await generateComponentMeta();
+    else
+      process.exit(ExitCode.InvalidArgument);
+  }
+}

package/dist/cli/actions/index.d.ts

@@ -0,0 +1,12 @@
+export * from './build';
+export * from './commit';
+export * from './dev';
+export * from './examples';
+export * from './fresh';
+export * from './generate';
+export * from './key';
+export * from './lint';
+export * from './make';
+export * from './release';
+export * from './test';
+export * from './update';

package/dist/cli/actions/index.mjs

@@ -0,0 +1,12 @@
+export * from "./build.mjs";
+export * from "./commit.mjs";
+export * from "./dev.mjs";
+export * from "./examples.mjs";
+export * from "./fresh.mjs";
+export * from "./generate.mjs";
+export * from "./key.mjs";
+export * from "./lint.mjs";
+export * from "./make.mjs";
+export * from "./release.mjs";
+export * from "./test.mjs";
+export * from "./update.mjs";

package/dist/cli/actions/key.d.ts

@@ -0,0 +1,2 @@
+export declare function generateAppKey(): Promise<string>;
+export declare function generate(): Promise<boolean>;

package/dist/cli/actions/key.mjs

@@ -0,0 +1,22 @@
+import { getRandomValues } from "node:crypto";
+import consola from "consola";
+import ezSpawn from "@jsdevtools/ez-spawn";
+import { projectPath } from "@stacksjs/paths";
+import { setEnvValue } from "@stacksjs/helpers";
+import { isFile } from "@stacksjs/fs";
+import utf8 from "crypto-js/enc-utf8";
+import base64 from "crypto-js/enc-base64";
+export async function generateAppKey() {
+  const random = getRandomValues(new Uint8Array(32));
+  const encodedWord = utf8.parse(random.toString());
+  const key = base64.stringify(encodedWord);
+  return `base64:${key}`;
+}
+export async function generate() {
+  consola.info("Setting random application key.");
+  if (!isFile(".env"))
+    await ezSpawn.async("cp .env.example .env", { stdio: "inherit", cwd: projectPath() });
+  await setEnvValue("APP_KEY", await generateAppKey());
+  consola.success("Application key set.");
+  return true;
+}

package/dist/cli/actions/lint.d.ts

@@ -0,0 +1,2 @@
+export declare function lint(debug?: 'ignore' | 'inherit'): Promise<void>;
+export declare function lintFix(debug?: 'ignore' | 'inherit'): Promise<void>;

package/dist/cli/actions/lint.mjs

@@ -0,0 +1,15 @@
+import consola from "consola";
+import { runNpmScript } from "@stacksjs/helpers";
+import { NpmScript } from "@stacksjs/types";
+export async function lint(debug = "inherit") {
+  consola.info("Linting your codebase...");
+  await runNpmScript(NpmScript.Lint, debug);
+  consola.success("Successfully linted your codebase.");
+}
+export async function lintFix(debug = "inherit") {
+  if (debug !== "ignore")
+    consola.info("Fixing lint errors...");
+  await runNpmScript(NpmScript.LintFix, debug);
+  if (debug !== "ignore")
+    consola.success("Fixed lint errors.");
+}

package/dist/cli/actions/make.d.ts

@@ -0,0 +1,5 @@
+export declare function component(name: string): Promise<void>;
+export declare function page(name: string): Promise<void>;
+export declare function fx(name: string): Promise<void>;
+export declare function language(language: string): Promise<void>;
+export declare function stack(name: string): Promise<void>;

package/dist/cli/actions/make.mjs

@@ -0,0 +1,97 @@
+import consola from "consola";
+import * as ezSpawn from "@jsdevtools/ez-spawn";
+import { writeTextFile } from "@stacksjs/fs";
+import { resolve } from "@stacksjs/paths";
+export async function component(name) {
+  consola.info("Creating your component...");
+  try {
+    await writeTextFile({
+      path: `./components/${name}.vue`,
+      data: `<script setup lang="ts">
+// eslint-disable-next-line no-console
+console.log('Hello World component created')
+<\/script>
+
+<template>
+  <div>
+    Some HTML block
+  </div>
+</template>
+`
+    });
+    consola.success(`Created the ${name} component.`);
+  } catch (err) {
+    consola.error(err);
+  }
+}
+export async function page(name) {
+  consola.info("Creating your component...");
+  try {
+    await writeTextFile({
+      path: `./pages/${name}.vue`,
+      data: `<script setup lang="ts">
+// eslint-disable-next-line no-console
+console.log('Hello World page created')
+<\/script>
+
+<template>
+  <div>
+    Visit http://127.0.0.1/${name}
+  </div>
+</template>
+`
+    });
+    consola.success(`Created the ${name} page.`);
+  } catch (err) {
+    consola.error(err);
+  }
+}
+export async function fx(name) {
+  consola.info("Creating your function...");
+  try {
+    await writeTextFile({
+      path: `./functions/${name}.ts`,
+      data: `// reactive state
+const ${name} = ref(0)
+
+// functions that mutate state and trigger updates
+function increment() {
+  ${name}.value++
+}
+
+export {
+  ${name},
+  increment,
+}
+`
+    });
+    consola.success(`Created the ${name} function.`);
+  } catch (err) {
+    consola.error(err);
+  }
+}
+export async function language(language2) {
+  consola.info("Creating your translation file...");
+  try {
+    await writeTextFile({
+      path: `./lang/${language2}.yml`,
+      data: `button:
+  text: Copy
+`
+    });
+    consola.success(`Created the ${language2} translation file.`);
+  } catch (err) {
+    consola.error(err);
+  }
+}
+export async function stack(name) {
+  consola.info("Creating your stack...");
+  try {
+    const path = resolve(process.cwd(), name);
+    await ezSpawn.async(`giget stacks ${path}`);
+    consola.success("Successfully scaffolded your project.");
+    consola.info(`cd ${path} && pnpm install`);
+  } catch (err) {
+    consola.error(err);
+  }
+}

package/dist/cli/actions/release.d.ts

@@ -0,0 +1 @@
+export declare function release(): Promise<void>;

package/dist/cli/actions/release.mjs

@@ -0,0 +1,8 @@
+import consola from "consola";
+import { runNpmScript } from "@stacksjs/helpers";
+import { NpmScript } from "@stacksjs/types";
+export async function release() {
+  consola.info("Releasing...");
+  await runNpmScript(NpmScript.Release);
+  consola.success("Triggered release workflow");
+}

package/dist/cli/actions/test.d.ts

@@ -0,0 +1,3 @@
+export declare function typecheck(): Promise<void>;
+export declare function runTestSuite(): Promise<void>;
+export declare function generateTestCoverageReport(): Promise<void>;

package/dist/cli/actions/test.mjs

@@ -0,0 +1,30 @@
+import consola from "consola";
+import { runNpmScript } from "@stacksjs/helpers";
+import { NpmScript } from "@stacksjs/types";
+export async function typecheck() {
+  consola.info("Typechecking your codebase...");
+  try {
+    await runNpmScript(NpmScript.TestTypes);
+    consola.success("Finished typechecking your codebase.");
+  } catch (error) {
+    consola.error(error);
+  }
+}
+export async function runTestSuite() {
+  consola.info("Running your test suite...");
+  try {
+    await runNpmScript(NpmScript.Test);
+    consola.success("Completed running the test suite.");
+  } catch (error) {
+    consola.error(error);
+  }
+}
+export async function generateTestCoverageReport() {
+  consola.info("Generating a test coverage report...");
+  try {
+    await runNpmScript(NpmScript.TestCoverage);
+    consola.success("Generated the test coverage report.");
+  } catch (error) {
+    consola.error(error);
+  }
+}

package/dist/cli/actions/types.d.ts

@@ -0,0 +1,9 @@
+export declare function generateTypes(): Promise<void>;
+export declare function fixTypes(): Promise<void>;
+export declare function generateLibEntries(): Promise<void>;
+export declare function generateVueCompat(): Promise<void>;
+export declare function generateWebTypes(): Promise<void>;
+export declare function generateVsCodeCustomData(): Promise<void>;
+export declare function generateIdeHelpers(): Promise<void>;
+export declare function generateComponentMeta(): Promise<void>;
+export declare function startGenerationProcess(options: any): Promise<void>;