astro-tractstack 2.0.0-rc.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025 At Risk Media
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# Tract Stack
+
+create your own adaptive website or newsletter
+
+the "free web press"
+no-code community engine
+
+by [At Risk Media](https://atriskmedia.com)
+
+## epistemic hypermedia server
+
+...a new species of web 2.0: an outcome of hybrid speciation.
+
+The `tractstack-go` package provides a backend server for the `astro-tractstack` integration
+
+Tract Stack makes it easy for non-technical people to build and grow adaptive websites that are fast, beautiful, SEO-ready, and accessible.
+
+Tract Stack is built on [Astro](https://astro.build/) with [HTMX](https://htmx.org/) and a [Golang](https://go.dev/) backend -- we recommend [Turso](https://app.turso.tech/) as database
+
+## Documentation
+
+Please visit [our docs](https://tractstack.org)
+
+For production deployment you'll need to prepare your server.
+
+_Quick Install_ in two steps:
+
+First install and run the go backend. It runs on port 8080 by default.
+
+```
+mkdir -p ~/src
+cd ~/src
+git clone https://github.com/AtRiskMedia/tractstack-go.git
+cd tractstack-go
+go build cmd/tractstack-go/main.go
+./tractstack-go
+```
+
+Next create an Astro starter then install Tract Stack as an integration:
+
+```
+cd ~/src
+pnpm create astro@latest my-tractstack --template minimal --typescript strict --install
+cd my-tractstack
+pnpm add astro-tractstack@latest
+npx create-tractstack
+pnpm dev
+```
+
+## Queries?
+
+Reach out at hello -at- tractstack -dot- com
+
+## License
+
+Functional Source License, Version 1.1, MIT Future License

package/astro.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="astro/client" />
+
+import type { PlayerJS } from '@/types/tractstack';
+
+declare module 'astro:transitions/client' {
+  export function navigate(url: string): void;
+}
+
+declare global {
+  interface ImportMeta {
+    env: {
+      PUBLIC_GO_BACKEND?: string;
+      PUBLIC_TENANTID?: string;
+      PUBLIC_ENABLE_MULTI_TENANT?: string;
+      DEV?: boolean;
+      PROD?: boolean;
+    };
+  }
+
+  interface Window {
+    initAnalyticsTracking: (storyfragmentId?: string) => Promise<void>;
+    htmx: any;
+    playerjs: PlayerJS;
+    TRACTSTACK_CONFIG: {
+      backendUrl: string;
+      tenantId: string;
+      sessionId: string;
+      storyfragmentId: string;
+      session?: {
+        isReady: boolean;
+      };
+    };
+    BELIEF_INITIALIZED?: boolean;
+    SSE_INITIALIZED?: boolean;
+    ANALYTICS_INITIALIZED?: boolean;
+    HTMX_CONFIGURED?: boolean;
+  }
+}
+
+declare namespace App {
+  interface Locals {
+    session?: Record<string, any>;
+    tenant?: {
+      id: string;
+      domain: string | null;
+      isMultiTenant: boolean;
+      isLocalhost: boolean;
+    };
+  }
+}
+
+// Astro script attributes
+declare global {
+  namespace astroHTML.JSX {
+    interface ScriptHTMLAttributes {
+      'is:inline'?: boolean;
+      'is:persist'?: boolean;
+      'define:vars'?: Record<string, any>;
+      crossorigin?: string;
+    }
+  }
+}
+
+export {};

package/bin/create-tractstack.js

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+
+import {
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+  existsSync,
+} from 'fs';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import prompts from 'prompts';
+import kleur from 'kleur';
+
+// Detect package manager
+function detectPackageManager() {
+  if (existsSync('pnpm-lock.yaml')) return 'pnpm';
+  if (existsSync('yarn.lock')) return 'yarn';
+  if (existsSync('package-lock.json')) return 'npm';
+
+  try {
+    const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
+    if (pkg.packageManager?.startsWith('pnpm')) return 'pnpm';
+    if (pkg.packageManager?.startsWith('yarn')) return 'yarn';
+  } catch {}
+
+  return 'pnpm';
+}
+
+async function main() {
+  // ASCII art
+  console.log(
+    kleur.blue().bold(`
+ ▄██▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄██▄▄▄▄▄▄▄██▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄
+  ██  ██ ██ ▀▀ ██ ██ ▀▀ ██ ██ ▀▀ ██ ▀▀ ██ ██ ▀▀ ██ ██
+  ██  ██▀█▄ ██▀██ ██ ▄▄ ██ ▀▀▀██ ██ ██▀██ ██ ▄▄ ██▀█▄
+  ██  ██ ██ ██▄██ ██▄██ ██ ██▄██ ██ ██▄██ ██▄██ ██ ██
+   ▀▀                   ▀▀       ▀▀             ▀▀ ▀▀▀
+`)
+  );
+
+  console.log(kleur.white().bold('  build your own adaptive website'));
+  console.log(kleur.reset('  made by At Risk Media\n'));
+
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  let includeExamples = false;
+  let enableMultiTenant = false;
+  let showHelp = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--examples') {
+      includeExamples = true;
+    } else if (args[i] === '--multi-tenant') {
+      enableMultiTenant = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      showHelp = true;
+    }
+  }
+
+  if (showHelp) {
+    console.log(`${kleur.bold('create-tractstack')} - Initialize a new TractStack project
+
+${kleur.bold('Usage:')}
+  create-tractstack [options]
+
+${kleur.bold('Options:')}
+  --examples      Include example components and collections route
+  --multi-tenant  Enable multi-tenant functionality for sandbox hosting
+  --help, -h     Show this help message
+
+${kleur.bold('Examples:')}
+  create-tractstack
+  create-tractstack --examples
+  create-tractstack --multi-tenant
+  create-tractstack --examples --multi-tenant`);
+    process.exit(0);
+  }
+
+  // Check if we're in an Astro project
+  if (!existsSync('./astro.config.mjs') && !existsSync('./astro.config.ts')) {
+    console.log(kleur.red("❌ This doesn't appear to be an Astro project."));
+    console.log('Please run this command in the root of your Astro project.\n');
+    console.log('To create a new Astro project with TractStack:');
+    console.log(kleur.cyan('pnpm create astro@latest my-tractstack-site'));
+    console.log(kleur.cyan('cd my-tractstack-site'));
+    console.log(kleur.cyan('npx create-tractstack'));
+    process.exit(1);
+  }
+
+  // Prompt for configuration
+  const responses = await prompts([
+    {
+      type: 'text',
+      name: 'goBackend',
+      message: 'TractStack Go backend URL:',
+      initial: 'http://localhost:8080',
+      validate: (value) => {
+        try {
+          new URL(value);
+          return true;
+        } catch {
+          return 'Please enter a valid URL';
+        }
+      },
+    },
+    {
+      type: 'text',
+      name: 'tenantId',
+      message: 'Tenant ID:',
+      initial: 'default',
+      validate: (value) => value.length > 0 || 'Tenant ID is required',
+    },
+    {
+      type: 'text',
+      name: 'goBackendPath',
+      message: 'TractStack Go backend path:',
+      initial: `${homedir()}/t8k-go-server/`,
+      validate: (value) => {
+        if (!value || value.trim().length === 0) {
+          return 'Backend path is required';
+        }
+        // Ensure it ends with trailing slash for consistency
+        return true;
+      },
+    },
+    {
+      type: 'confirm',
+      name: 'includeExamples',
+      message:
+        'Include CodeHook examples? (custom components, collections route)',
+      initial: includeExamples,
+    },
+    {
+      type: 'confirm',
+      name: 'enableMultiTenant',
+      message: 'Enable multi-tenant functionality?',
+      initial: enableMultiTenant,
+    },
+  ]);
+
+  if (!responses.goBackend || !responses.tenantId) {
+    console.log(kleur.red('\n❌ Setup cancelled.'));
+    process.exit(1);
+  }
+
+  // Create .env file
+  const envContent = `# TractStack Configuration
+PUBLIC_GO_BACKEND="${responses.goBackend}"
+PUBLIC_TENANTID="${responses.tenantId}"
+PRIVATE_GO_BACKEND_PATH="${responses.goBackendPath.endsWith('/') ? responses.goBackendPath : responses.goBackendPath + '/'}"
+`;
+
+  try {
+    writeFileSync('.env', envContent);
+    console.log(kleur.green('✅ Created .env file'));
+  } catch (error) {
+    console.log(kleur.red('❌ Failed to create .env file:', error.message));
+    process.exit(1);
+  }
+
+  // Install dependencies
+  const packageManager = detectPackageManager();
+  const addCommand =
+    packageManager === 'pnpm' ? 'pnpm add' : `${packageManager} add`;
+
+  console.log(kleur.cyan('\nInstalling dependencies...'));
+  try {
+    // Install React and Node adapter
+    execSync(
+      `${addCommand} react@^18.3.1 react-dom@^18.3.1 @astrojs/react@^4.0.0 @astrojs/node@^9.4.3`,
+      { stdio: 'inherit' }
+    );
+    console.log(kleur.green('✅ React and Node adapter installed'));
+
+    // Install core dependencies
+    execSync(
+      `${addCommand} @nanostores/react@^1.0.0 nanostores@^1.0.1 @nanostores/persistent ulid`,
+      {
+        stdio: 'inherit',
+      }
+    );
+    console.log(kleur.green('✅ State management installed'));
+
+    // Install UI components
+    execSync(
+      `${addCommand} @ark-ui/react@^5.21.0 @heroicons/react@^2.1.1 @internationalized/date@3.8.2`,
+      {
+        stdio: 'inherit',
+      }
+    );
+    console.log(kleur.green('✅ UI components installed'));
+
+    // Install visualization dependencies
+    execSync(
+      `${addCommand} d3@^7.9.0 d3-sankey@^0.12.3 recharts@^3.1.2 player.js@^0.1.0 tinycolor2 html-to-image`,
+      {
+        stdio: 'inherit',
+      }
+    );
+    console.log(kleur.green('✅ Visualization dependencies installed'));
+
+    // Install additional dependencies
+    execSync(`${addCommand} path-to-regexp@^8.0.0`, { stdio: 'inherit' });
+    console.log(kleur.green('✅ Additional dependencies installed'));
+
+    // Install dev dependencies
+    execSync(
+      `${addCommand} -D @types/node@^22.18.0 @types/react@^18.3.11 @types/react-dom@^18.3.0 @types/d3@^7.4.3 @types/d3-sankey@^0.12.3 prettier@^3.3.3 prettier-plugin-astro@^0.14.1 prettier-plugin-tailwindcss@^0.6.8 typescript@^5.9.2 @types/tinycolor2 @mhsdesign/jit-browser-tailwindcss`,
+      { stdio: 'inherit' }
+    );
+    console.log(kleur.green('✅ Dev dependencies installed'));
+  } catch (error) {
+    console.log(kleur.red('❌ Failed to install dependencies'));
+    console.log('Please run manually:');
+    console.log(
+      kleur.cyan(
+        `${addCommand} react@^18.3.1 react-dom@^18.3.1 @astrojs/react@^4.0.0 @astrojs/node@^9.4.3 @nanostores/react@^1.0.0 nanostores@^1.0.1 @nanostores/persistent ulid @ark-ui/react@^5.21.0 @heroicons/react@^2.1.1 @internationalized/date@3.8.2 d3@^7.9.0 d3-sankey@^0.12.3 recharts@^3.1.2 player.js@^0.1.0 tinycolor2 html-to-image path-to-regexp@^8.0.0`
+      )
+    );
+    console.log(
+      kleur.cyan(
+        `${addCommand} -D @types/node@^22.18.0 @types/react@^18.3.11 @types/react-dom@^18.3.0 @types/d3@^7.4.3 @types/d3-sankey@^0.12.3 prettier@^3.3.3 prettier-plugin-astro@^0.14.1 prettier-plugin-tailwindcss@^0.6.8 typescript@^5.9.2 @types/tinycolor2 @mhsdesign/jit-browser-tailwindcss`
+      )
+    );
+    process.exit(1);
+  }
+
+  // Create .gitignore
+  const gitignoreContent = `# Node.js dependencies
+node_modules/
+.pnpm-store/
+
+# Astro build output
+dist/
+.astro/
+
+# Environment variables
+.env
+.env.local
+.env.production
+
+# OS-specific files
+.DS_Store
+Thumbs.db
+
+# Editor directories and files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# TypeScript
+*.tsbuildinfo
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# TractStack specific
+public/media/
+src/content/generated/
+`;
+
+  if (!existsSync('.gitignore')) {
+    writeFileSync('.gitignore', gitignoreContent);
+    console.log(kleur.green('✅ Created .gitignore'));
+  }
+
+  // Create directories
+  const dirs = [
+    'src',
+    'src/components',
+    'src/layouts',
+    'src/pages',
+    'src/types',
+    'src/utils',
+    'src/stores',
+    'src/hooks',
+    'public',
+    'public/brand',
+    'public/socials',
+  ];
+
+  dirs.forEach((dir) => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  });
+
+  console.log(kleur.green('✅ Created directory structure'));
+
+  // Remove unwanted index.astro
+  const indexAstroPath = resolve('src/pages/index.astro');
+  if (existsSync(indexAstroPath)) {
+    unlinkSync(indexAstroPath);
+    console.log(kleur.green('✅ Removed src/pages/index.astro'));
+  } else {
+    console.log(kleur.yellow('⚠️ No src/pages/index.astro found to remove'));
+  }
+
+  // Update Astro config
+  async function updateAstroConfig() {
+    const configs = ['astro.config.mjs', 'astro.config.ts'];
+    let configFile = null;
+
+    for (const config of configs) {
+      if (existsSync(config)) {
+        configFile = config;
+        break;
+      }
+    }
+
+    if (!configFile) {
+      console.log(kleur.red('❌ No Astro config file found'));
+      return;
+    }
+
+    try {
+      let newContent;
+      if (configFile.endsWith('.ts')) {
+        newContent = `import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import node from '@astrojs/node';
+import tractstack from 'astro-tractstack';
+
+export default defineConfig({
+  integrations: [
+    react(),
+    tractstack({
+      includeExamples: ${responses.includeExamples},
+      enableMultiTenant: ${responses.enableMultiTenant},
+    }),
+  ],
+  output: 'server',
+  adapter: node({
+    mode: 'standalone',
+  }),
+});`;
+      } else {
+        newContent = `import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import node from '@astrojs/node';
+import tractstack from 'astro-tractstack';
+
+export default defineConfig({
+  integrations: [
+    react(),
+    tractstack({
+      includeExamples: ${responses.includeExamples},
+      enableMultiTenant: ${responses.enableMultiTenant},
+    }),
+  ],
+  output: 'server',
+  adapter: node({
+    mode: 'standalone',
+  }),
+});`;
+      }
+
+      writeFileSync(configFile, newContent);
+      console.log(kleur.green(`✅ Updated ${configFile}`));
+    } catch (error) {
+      console.log(
+        kleur.red(`❌ Failed to update ${configFile}:`, error.message)
+      );
+    }
+  }
+
+  // Create prettier config
+  const prettierConfig = `{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "plugins": [
+    "prettier-plugin-astro",
+    "prettier-plugin-tailwindcss"
+  ],
+  "overrides": [
+    {
+      "files": "*.astro",
+      "options": {
+        "parser": "astro"
+      }
+    }
+  ]
+}`;
+
+  if (!existsSync('.prettierrc')) {
+    writeFileSync('.prettierrc', prettierConfig);
+    console.log(kleur.green('✅ Created Prettier config'));
+  }
+
+  // Create tsconfig.json
+  const tsConfig = `{
+    "extends": "astro/tsconfigs/strict",
+    "compilerOptions": {
+      "baseUrl": ".",
+      "paths": { "@/*": ["src/*"] },
+      "types": ["astro/client", "@astrojs/react", "node", "@types/react", "@types/react-dom", "@types/tinycolor2"]
+    },
+    "include": ["src/**/*", "public/**/*", "tailwind.config.cjs"],
+    "exclude": ["node_modules", "dist", ".astro"]
+  }`;
+  writeFileSync('tsconfig.json', tsConfig);
+  console.log(kleur.green('✅ Updated tsconfig.json'));
+
+  // Update package.json
+  try {
+    const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
+    pkg.scripts = {
+      ...pkg.scripts,
+      dev: 'astro dev',
+      build: 'astro build',
+      format: 'prettier --write .',
+      'format:check': 'prettier --check .',
+    };
+
+    writeFileSync('package.json', JSON.stringify(pkg, null, 2));
+    console.log(kleur.green('✅ Updated package.json scripts'));
+  } catch (error) {
+    console.log(kleur.red('❌ Failed to update package.json:', error.message));
+  }
+
+  await updateAstroConfig();
+
+  // Initialize TractStack integration and format project files
+  try {
+    console.log(kleur.cyan('🔧 Initializing TractStack integration...'));
+    execSync(`${packageManager} astro build`, { stdio: 'inherit' });
+    console.log(kleur.green('✅ TractStack templates injected'));
+
+    //execSync(`${packageManager} format`, { stdio: 'inherit' });
+    //console.log(kleur.green('✅ Formatted project files'));
+  } catch (error) {
+    console.log(
+      kleur.yellow(
+        '⚠️ Setup completed, but run `pnpm astro build && pnpm format` to finish'
+      )
+    );
+  }
+
+  // Success message
+  console.log(kleur.green('\n🎉 TractStack setup complete!'));
+
+  const runCommand =
+    packageManager === 'pnpm' ? 'pnpm run' : `${packageManager} run`;
+
+  console.log('\nNext steps:');
+  console.log(kleur.cyan('1. Start your Go backend:'));
+  console.log('   tractstack-go');
+  console.log(kleur.cyan('2. Start your Astro development server:'));
+  console.log(`   ${runCommand} dev`);
+
+  if (responses.enableMultiTenant) {
+    console.log('\n' + kleur.bold('Multi-tenant features enabled:'));
+    console.log(`  • Tenant registration: ${kleur.cyan('/sandbox/register')}`);
+    console.log(`  • Subdomain routing middleware added`);
+    console.log(`  • Admin-only tenant management`);
+    console.log(
+      `\n${kleur.yellow('Note:')} Make sure your Go backend has ENABLE_MULTI_TENANT=true`
+    );
+  }
+
+  if (responses.includeExamples) {
+    console.log(`\n${kleur.bold('Example components included:')}`);
+    console.log(
+      `  • Collections route: ${kleur.cyan('/collections/[param1]')}`
+    );
+    console.log(`  • Custom components and CodeHooks`);
+  }
+
+  console.log('\n📚 Documentation: https://tractstack.org/docs');
+}
+
+main().catch(console.error);