figala 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Figala authors
+
+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

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# figala
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command line tool for [Figala](https://github.com/getfigala), a European app platform.
+
+**Status:** early version. The platform is not publicly available yet, so `figala deploy` and the other platform
+commands do not exist in this release. What works today runs entirely on your machine and sends nothing anywhere.
+
+## Install
+
+```sh
+npm install -g figala
+```
+
+Requires Node.js 20 or newer. No dependencies.
+
+## Commands
+
+### `figala init [dir]`
+
+Looks at a project folder and writes a `figala.toml` describing how to build and run it.
+
+```sh
+figala init
+figala init ./apps/web --project recipes
+figala init --json
+```
+
+It recognises Next.js, Nuxt, Astro, SvelteKit, Remix, Vite, Express, Fastify, NestJS, Django, Flask, FastAPI and
+projects with a `Dockerfile`, and suggests a Postgres database when it finds a Postgres client or ORM. It reads
+`package.json`, `requirements.txt`, `pyproject.toml` and the lockfile names. It never reads `.env` files, and secrets do
+not belong in `figala.toml`.
+
+An existing `figala.toml` is left alone unless you pass `--force`. Check the result before you commit it: detection
+is a suggestion.
+
+| Option | Meaning |
+|---|---|
+| `--project <name>` | project name; by default it comes from `package.json` or the folder name |
+| `--force` | overwrite an existing `figala.toml` |
+| `--stdout` | print the file instead of writing it |
+| `--json` | machine-readable output |
+
+### `figala check-name <project>`
+
+Checks a project name against the naming rules: 3 to 24 characters, `a-z`, `0-9` and `-`, starts with a letter, does
+not end with `-`, no `--`, and not a reserved name. It does not check whether the name is taken.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | the command failed, for example `figala.toml` already exists |
+| 2 | wrong usage or invalid name |
+
+## License
+
+MIT

package/bin/figala.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { detectProject } from '../src/detect.js';
+import { projectNameProblems, suggestProjectName } from '../src/names.js';
+import { renderToml } from '../src/toml.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const HELP = `figala ${version}
+
+Usage:
+  figala init [dir] [--project <name>] [--force] [--stdout] [--json]
+  figala check-name <project> [--json]
+  figala --version
+
+This early version works locally and sends nothing anywhere. The platform is not
+publicly available yet, so deploy and the other platform commands are not included.
+`;
+
+class UsageError extends Error {}
+
+function report(json, data, text) {
+  console.log(json ? JSON.stringify(data) : text);
+}
+
+function init(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      project: { type: 'string' },
+      force: { type: 'boolean', default: false },
+      stdout: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+  });
+  if (positionals.length > 1) throw new UsageError('init takes one folder');
+  const dir = resolve(positionals[0] ?? '.');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new UsageError(`not a folder: ${dir}`);
+
+  const found = detectProject(dir);
+  const project = values.project ?? suggestProjectName(found.packageName ?? '') ?? suggestProjectName(basename(dir));
+  if (!project) throw new UsageError('could not derive a valid project name; pass --project <name>');
+  const problems = projectNameProblems(project);
+  if (problems.length > 0) throw new UsageError(`project name "${project}" ${problems.join(', ')}`);
+
+  const text = renderToml(project, found);
+  const target = join(dir, 'figala.toml');
+  const data = { project, framework: found.framework, runtime: found.runtime, type: found.type, postgres: found.wantsPostgres };
+  if (values.stdout) {
+    if (values.json) report(true, { ...data, toml: text });
+    else process.stdout.write(text);
+    return 0;
+  }
+  if (existsSync(target) && !values.force) {
+    report(values.json, { ...data, written: false, error: 'figala.toml already exists' },
+      'figala.toml already exists; pass --force to overwrite it.');
+    return 1;
+  }
+  writeFileSync(target, text);
+  report(values.json, { ...data, written: true, path: target },
+    `Wrote ${target}\nDetected: ${found.framework ?? found.runtime ?? 'nothing specific'}. Check the file before you commit it.`);
+  return 0;
+}
+
+function checkName(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: { json: { type: 'boolean', default: false } },
+  });
+  if (positionals.length !== 1) throw new UsageError('check-name takes one name');
+  const problems = projectNameProblems(positionals[0]);
+  report(values.json, { name: positionals[0], valid: problems.length === 0, problems },
+    problems.length === 0 ? `${positionals[0]} follows the naming rules.` : `${positionals[0]} ${problems.join(', ')}.`);
+  return problems.length === 0 ? 0 : 2;
+}
+
+function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+    console.log(HELP);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    console.log(version);
+    return 0;
+  }
+  try {
+    if (command === 'init') return init(rest);
+    if (command === 'check-name') return checkName(rest);
+    throw new UsageError(`unknown command: ${command}`);
+  } catch (error) {
+    if (error instanceof UsageError || error.code?.startsWith('ERR_PARSE_ARGS')) {
+      console.error(`${error.message}\n\n${HELP}`);
+      return 2;
+    }
+    console.error(error.message);
+    return 1;
+  }
+}
+
+process.exitCode = main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "figala",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Command line tool for Figala, a European app platform. This early version generates and checks project configuration.",
+  "keywords": ["figala", "deploy", "paas", "cli", "figala.toml"],
+  "license": "MIT",
+  "author": "Figala",
+  "homepage": "https://github.com/getfigala/cli#readme",
+  "bugs": "https://github.com/getfigala/cli/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getfigala/cli.git"
+  },
+  "type": "module",
+  "bin": {
+    "figala": "bin/figala.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/detect.js

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The first match wins, so meta-frameworks come before the libraries they are built on.
+const NODE_FRAMEWORKS = [
+  { dep: 'next', framework: 'nextjs', type: 'web', port: 3000 },
+  { dep: 'nuxt', framework: 'nuxt', type: 'web', port: 3000 },
+  { dep: '@remix-run/node', framework: 'remix', type: 'web', port: 3000 },
+  { dep: '@sveltejs/kit', framework: 'sveltekit', type: 'web', port: 3000 },
+  { dep: 'astro', framework: 'astro', type: 'static' },
+  { dep: '@nestjs/core', framework: 'nestjs', type: 'web', port: 3000 },
+  { dep: 'fastify', framework: 'fastify', type: 'web', port: 3000 },
+  { dep: 'express', framework: 'express', type: 'web', port: 3000 },
+  { dep: 'vite', framework: 'vite', type: 'static' },
+];
+
+const PYTHON_FRAMEWORKS = [
+  { dep: 'django', framework: 'django', type: 'web', port: 8000 },
+  { dep: 'fastapi', framework: 'fastapi', type: 'web', port: 8000 },
+  { dep: 'flask', framework: 'flask', type: 'web', port: 8000 },
+];
+
+const POSTGRES_NODE = ['pg', 'postgres', 'prisma', '@prisma/client', 'drizzle-orm', 'typeorm', 'sequelize', 'knex'];
+const POSTGRES_PYTHON = ['psycopg', 'psycopg2', 'psycopg2-binary', 'asyncpg', 'sqlalchemy', 'django'];
+
+const LOCKFILES = [
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['bun.lock', 'bun'],
+  ['bun.lockb', 'bun'],
+  ['package-lock.json', 'npm'],
+];
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function pythonDependencies(dir) {
+  const names = new Set();
+  for (const file of ['requirements.txt', 'pyproject.toml']) {
+    const path = join(dir, file);
+    if (!existsSync(path)) continue;
+    for (const match of readFileSync(path, 'utf8').matchAll(/^[\s"']*([A-Za-z][A-Za-z0-9._-]*)/gm)) {
+      names.add(match[1].toLowerCase());
+    }
+  }
+  return names;
+}
+
+/** Inspects a folder and returns what it found. Reads only manifests, never .env files. */
+export function detectProject(dir) {
+  const result = {
+    runtime: null,
+    framework: null,
+    type: 'web',
+    port: null,
+    packageManager: null,
+    start: null,
+    build: null,
+    wantsPostgres: false,
+    packageName: null,
+    dockerfile: existsSync(join(dir, 'Dockerfile')),
+  };
+
+  const pkg = readJson(join(dir, 'package.json'));
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    result.runtime = 'node';
+    result.packageName = typeof pkg.name === 'string' ? pkg.name : null;
+    result.packageManager = LOCKFILES.find(([file]) => existsSync(join(dir, file)))?.[1] ?? 'npm';
+    const run = result.packageManager === 'npm' ? 'npm run' : result.packageManager;
+    const known = NODE_FRAMEWORKS.find(({ dep }) => dep in deps);
+    if (known) Object.assign(result, { framework: known.framework, type: known.type, port: known.port ?? null });
+    if (pkg.scripts?.build) result.build = `${run} build`;
+    if (pkg.scripts?.start) result.start = result.packageManager === 'npm' ? 'npm start' : `${run} start`;
+    result.wantsPostgres = POSTGRES_NODE.some((name) => name in deps);
+    return result;
+  }
+
+  const python = pythonDependencies(dir);
+  if (python.size > 0) {
+    result.runtime = 'python';
+    const known = PYTHON_FRAMEWORKS.find(({ dep }) => python.has(dep));
+    if (known) Object.assign(result, { framework: known.framework, type: known.type, port: known.port });
+    result.wantsPostgres = POSTGRES_PYTHON.some((name) => python.has(name));
+  }
+  return result;
+}

package/src/names.js

@@ -0,0 +1,30 @@
+const RESERVED = new Set([
+  'www', 'api', 'app', 'admin', 'status', 'mail', 'db', 'cdn', 'cname', 'docs', 'figala', 'getfigala',
+]);
+
+const SHAPE = /^[a-z](?:[a-z0-9-]*[a-z0-9])?$/;
+
+/** Returns a list of problems; an empty list means the project name is acceptable. */
+export function projectNameProblems(name) {
+  const problems = [];
+  if (name.length < 3 || name.length > 24) problems.push('must be 3 to 24 characters');
+  if (!SHAPE.test(name)) problems.push('may use a-z, 0-9 and -, must start with a letter and not end with -');
+  if (name.includes('--')) problems.push('must not contain --');
+  if (RESERVED.has(name)) problems.push('is a reserved name');
+  return problems;
+}
+
+/** Turns a folder or package name into the closest valid project name, or null if there is none. */
+export function suggestProjectName(raw) {
+  const cleaned = String(raw)
+    .replace(/^@[^/]+\//, '')
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[^a-z]+/, '')
+    .slice(0, 24)
+    .replace(/-+$/, '');
+  return projectNameProblems(cleaned).length === 0 ? cleaned : null;
+}

package/src/toml.js

@@ -0,0 +1,24 @@
+// JSON string escaping is valid for TOML basic strings.
+const quote = (value) => JSON.stringify(value);
+
+/** Writes the figala.toml text for a detected project. */
+export function renderToml(project, found) {
+  const lines = [
+    '# Generated by figala init. Detection is a suggestion, so check this file before you commit it.',
+    '# Secrets do not belong here; set them with the platform instead.',
+    `project = ${quote(project)}`,
+    '',
+    '[services.web]',
+    `type = ${quote(found.type)}`,
+    'primary = true',
+  ];
+  if (found.build) lines.push(`build = ${quote(found.build)}`);
+  if (found.start && found.type !== 'static') lines.push(`start = ${quote(found.start)}`);
+  if (found.port && found.type !== 'static') lines.push(`port = ${found.port}`);
+  lines.push('size = "512mb"');
+  if (found.dockerfile) lines.push('# A Dockerfile was found; it is used for the build when present.');
+  if (found.wantsPostgres) {
+    lines.push('', '[services.web.env]', 'DATABASE_URL = "${{db.DATABASE_URL}}"', '', '[databases.db]', 'engine = "postgres"');
+  }
+  return `${lines.join('\n')}\n`;
+}