ntc-dev-kit 1.3.1__tar.gz → 1.4.0__tar.gz

{ntc_dev_kit-1.3.1/ntc_dev_kit.egg-info → ntc_dev_kit-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ntc-dev-kit
-Version: 1.3.1
+Version: 1.4.0
 Summary: Nexent Toolkit Console - A CLI tool for scaffolding Django REST Framework, React, Next.js, and Flutter projects
 Home-page: https://github.com/nexent/ntc
 Author: Nexent
@@ -163,11 +163,41 @@ In `ntc start`, **All** is a grid of up to four terminals, one per app (**[** an
 through more), with each app's port and status on its border and its output colour-coded: errors
 red, warnings amber, ready/compiled green, HTTP status codes by class. **Tab** moves between the
 terminals and the keys act on the focused one: **r** restarts, **s** stops or starts, **o** opens
-it in the browser, **i** types into it (Flutter's `r` hot reload), **c** clears, **Enter** opens it
+it in the browser (**Ctrl+O** opens every app that's running), **i** types into it (Flutter's `r` hot reload), **c** clears, **Enter** opens it
 full screen (**Esc** comes back). **1-9** jump to an app's own tab, **0** back to all, **q** quits
 and stops everything. Apps wait for the ones they `need` (the backend) before starting, and a port
 that's already taken is reported instead of crashing.
 
+#### The backend allows the frontends
+
+Whenever `ntc start` runs a Django app, it adds every frontend's origin (`http://127.0.0.1:<port>`
+and `http://localhost:<port>`) to the backend's `CORS_ALLOWED_ORIGINS` and `CSRF_TRUSTED_ORIGINS`,
+so the browser apps can call the API whatever ports they're on. It reads which environment
+variables the settings use and keeps what they already allow (from the environment, the app's
+`.env`, or the settings' default); only the backend's process gets the result, nothing is edited.
+A setting written out in the settings (not read from the environment) can't be extended from
+outside: the backend's terminal then says which origins to add. `allow_origins = false` in the
+app's section turns this off. New workspaces also get the origins in the backend's `.env`, for
+running it on its own.
+
+#### Existing projects: `ntc adopt`
+
+Apps that weren't made by ntc can run with it too. In the folder that holds them:
+
+```bash
+ntc adopt             # finds the apps, shows what it found, writes ntc.toml
+ntc adopt --dry-run   # just show
+```
+
+It recognises Django (`manage.py`), Next.js, Vite and other Node apps (`package.json` with a
+`dev`/`start` script) and Flutter, and keeps how each already runs: its package manager (npm,
+pnpm, yarn, bun), its `dev` script and port (a port clash is moved with `--port`), and its Python
+environment (`env/`, `venv/`, `.venv/`, or a conda env named after the project). Folders that
+aren't apps (documents, tooling) are left out, and a shared name prefix is dropped
+(`shop-backend` → `backend`). Only `ntc.toml` is written: nothing in the apps changes, no env
+values are overridden, and setup never runs `migrate` (the project's `.env` may point at a shared
+database). `ntc setup` copies `.env.example` when an app has no env file yet.
+
 `ntc clean` only removes what the tools rebuild (`.next`, `dist`, `__pycache__`, caches; with
 `--deep` also `node_modules` and `env`), never anything git tracks, and skips apps that are running.
 `--dry-run` shows what would go.

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/README.md

@@ -122,11 +122,41 @@ In `ntc start`, **All** is a grid of up to four terminals, one per app (**[** an
 through more), with each app's port and status on its border and its output colour-coded: errors
 red, warnings amber, ready/compiled green, HTTP status codes by class. **Tab** moves between the
 terminals and the keys act on the focused one: **r** restarts, **s** stops or starts, **o** opens
-it in the browser, **i** types into it (Flutter's `r` hot reload), **c** clears, **Enter** opens it
+it in the browser (**Ctrl+O** opens every app that's running), **i** types into it (Flutter's `r` hot reload), **c** clears, **Enter** opens it
 full screen (**Esc** comes back). **1-9** jump to an app's own tab, **0** back to all, **q** quits
 and stops everything. Apps wait for the ones they `need` (the backend) before starting, and a port
 that's already taken is reported instead of crashing.
 
+#### The backend allows the frontends
+
+Whenever `ntc start` runs a Django app, it adds every frontend's origin (`http://127.0.0.1:<port>`
+and `http://localhost:<port>`) to the backend's `CORS_ALLOWED_ORIGINS` and `CSRF_TRUSTED_ORIGINS`,
+so the browser apps can call the API whatever ports they're on. It reads which environment
+variables the settings use and keeps what they already allow (from the environment, the app's
+`.env`, or the settings' default); only the backend's process gets the result, nothing is edited.
+A setting written out in the settings (not read from the environment) can't be extended from
+outside: the backend's terminal then says which origins to add. `allow_origins = false` in the
+app's section turns this off. New workspaces also get the origins in the backend's `.env`, for
+running it on its own.
+
+#### Existing projects: `ntc adopt`
+
+Apps that weren't made by ntc can run with it too. In the folder that holds them:
+
+```bash
+ntc adopt             # finds the apps, shows what it found, writes ntc.toml
+ntc adopt --dry-run   # just show
+```
+
+It recognises Django (`manage.py`), Next.js, Vite and other Node apps (`package.json` with a
+`dev`/`start` script) and Flutter, and keeps how each already runs: its package manager (npm,
+pnpm, yarn, bun), its `dev` script and port (a port clash is moved with `--port`), and its Python
+environment (`env/`, `venv/`, `.venv/`, or a conda env named after the project). Folders that
+aren't apps (documents, tooling) are left out, and a shared name prefix is dropped
+(`shop-backend` → `backend`). Only `ntc.toml` is written: nothing in the apps changes, no env
+values are overridden, and setup never runs `migrate` (the project's `.env` may point at a shared
+database). `ntc setup` copies `.env.example` when an app has no env file yet.
+
 `ntc clean` only removes what the tools rebuild (`.next`, `dist`, `__pycache__`, caches; with
 `--deep` also `node_modules` and `env`), never anything git tracks, and skips apps that are running.
 `--dry-run` shows what would go.

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/ntc/__init__.py

@@ -1,5 +1,5 @@
 """NTC - Nexent Toolkit Console."""
 
-__version__ = "1.3.1"
+__version__ = "1.4.0"
 __author__ = "Nexent"
 __license__ = "MIT"

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/ntc/cli_enhanced.py

@@ -363,6 +363,10 @@ Examples:
     add_install.add_argument("--install", dest="install", action="store_true", default=None)
     add_install.add_argument("--no-install", dest="install", action="store_false")
     add_parser.add_argument("--yes", "-y", action="store_true", help="Don't ask")
+    adopt_parser = subparsers.add_parser("adopt", help="Run existing apps (not made by ntc) with ntc: writes ntc.toml")
+    adopt_parser.add_argument("path", nargs="?", help="The folder holding the apps (default: current folder)")
+    adopt_parser.add_argument("--dry-run", action="store_true", help="Show what was found, write nothing")
+    adopt_parser.add_argument("--yes", "-y", action="store_true", help="Don't ask: take the best guesses")
     setup_parser = subparsers.add_parser("setup", help="Install the workspace's apps (after a clone or a deep clean)")
     setup_parser.add_argument("apps", nargs="*", help="Only these apps")
     clean_parser = subparsers.add_parser("clean", help="Delete build output and caches; say how much space it freed")
@@ -424,6 +428,9 @@ Examples:
     elif args.command == "start":
         from ntc.workspace.start import run as run_start
         sys.exit(0 if run_start(args.apps, plain=args.plain) else 1)
+    elif args.command == "adopt":
+        from ntc.workspace.adopt import run as run_adopt
+        sys.exit(0 if run_adopt(args.path, assume_yes=args.yes, dry_run=args.dry_run) else 1)
     elif args.command == "setup":
         from ntc.workspace.setup import run as run_setup
         sys.exit(0 if run_setup(args.apps) else 1)

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/ntc/templates/nextjs/next.config.js

@@ -1,6 +1,11 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   reactStrictMode: true,
+  // The dev server serves on localhost; opened as 127.0.0.1 (as ntc start may), its hot reload
+  // would be blocked as cross-origin.
+  allowedDevOrigins: ['127.0.0.1', 'localhost'],
+  // The project folder is the root, even when a package-lock.json sits in a folder above it.
+  turbopack: { root: __dirname },
   images: {
     // Hosts next/image may load from, e.g.
     //   { protocol: 'https', hostname: 'media.example.com', pathname: '/**' }

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/ntc/templates/react_admin/vite.config.ts

@@ -1,13 +1,13 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
-import path from 'path'
+import { fileURLToPath } from 'node:url'
 
 export default defineConfig({
   plugins: [react(), tailwindcss()],
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, './src'),
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
     },
   },
 })

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/ntc/templates/react_structure/App.css

@@ -42,6 +42,18 @@
   background: rgba(244, 67, 54, 0.3);
 }
 
+.status-indicator.degraded {
+  background: rgba(255, 152, 0, 0.35);
+}
+
+.api-problems,
+.api-hint {
+  margin-top: 0.75rem;
+  list-style: none;
+  font-size: 0.9rem;
+  opacity: 0.9;
+}
+
 .status-indicator.checking {
   background: rgba(255, 193, 7, 0.3);
 }

ntc_dev_kit-1.4.0/ntc/templates/react_structure/src/App.tsx

@@ -0,0 +1,79 @@
+import { useState, useEffect } from 'react'
+import './App.css'
+import Header from './components/Header'
+import axios from 'axios'
+import { apiService } from './services/api'
+import { API_BASE_URL } from './utils/constants'
+
+type ApiStatus = 'checking' | 'connected' | 'degraded' | 'disconnected'
+
+function App() {
+  const [apiStatus, setApiStatus] = useState<ApiStatus>('checking')
+  const [problems, setProblems] = useState<string[]>([])
+
+  useEffect(() => {
+    // The ntc Django template's /health/ answers 503 when the API is up but a service it uses
+    // (the database, Redis) isn't: that is "connected, degraded", not "disconnected".
+    const checkApiConnection = async () => {
+      try {
+        await apiService.get('/health/')
+        setApiStatus('connected')
+      } catch (error) {
+        const response = axios.isAxiosError(error) ? error.response : undefined
+        if (!response) {
+          setApiStatus('disconnected')  // nothing answered: not running, wrong URL, or CORS
+          return
+        }
+        const services = (response.data?.errors ?? {}) as Record<string, { ok?: boolean; problem?: string }>
+        setProblems(Object.entries(services)
+          .filter(([, service]) => service && typeof service === 'object' && service.ok === false)
+          .map(([name, service]) => `${name}: ${service.problem}`))
+        setApiStatus('degraded')
+      }
+    }
+
+    checkApiConnection()
+  }, [])
+
+  return (
+    <div className="App">
+      <Header />
+      <main className="App-main">
+        <div className="welcome-section">
+          <h1>Welcome to {import.meta.env.VITE_APP_NAME || '{project_name}'}</h1>
+          <p>Your API-driven React application is ready!</p>
+          
+          <div className="api-status">
+            <h3>API Connection Status:</h3>
+            <div className={`status-indicator ${apiStatus}`}>
+              {apiStatus === 'checking' && '🔄 Checking...'}
+              {apiStatus === 'connected' && '✅ Connected'}
+              {apiStatus === 'degraded' && '⚠️ Connected, but a service is down'}
+              {apiStatus === 'disconnected' && '❌ Disconnected'}
+            </div>
+            {problems.length > 0 && (
+              <ul className="api-problems">
+                {problems.map((problem) => <li key={problem}>{problem}</li>)}
+              </ul>
+            )}
+            {apiStatus === 'disconnected' && (
+              <p className="api-hint">Is the backend running? It should be at {API_BASE_URL}.</p>
+            )}
+          </div>
+
+          <div className="getting-started">
+            <h3>Getting Started:</h3>
+            <ol>
+              <li>Start your backend API server</li>
+              <li>Update API_BASE_URL in .env file if needed</li>
+              <li>Begin building your components in src/components/</li>
+              <li>Add API calls using the apiService in src/services/</li>
+            </ol>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}
+
+export default App

ntc_dev_kit-1.4.0/ntc/templates/react_structure/src/utils/constants.ts

@@ -0,0 +1 @@
+export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://127.0.0.1:8000/api/v1'  // the ntc Django template's API

ntc_dev_kit-1.4.0/ntc/templates/react_structure/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { fileURLToPath } from 'node:url'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      // Not __dirname: Vite's native config loader (the coming default) runs it as ESM.
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+})

{ntc_dev_kit-1.3.1 → ntc_dev_kit-1.4.0}/ntc/wizard.py

@@ -255,6 +255,12 @@ def run(technology=None, name=None, path=None, with_auth=None, env_choice=None,
     inside = workspace_config.find_root()
     if inside and not apps and technology is None:
         prompts.info(f"You're in the {os.path.basename(inside)} workspace - `ntc add` adds an app to it.")
+    elif not inside and not apps and technology is None:
+        from ntc.workspace.adopt import detect
+        existing, _ = detect(os.getcwd())
+        if existing:
+            prompts.info(f"This folder already has {len(existing)} app{'s' if len(existing) != 1 else ''} "
+                         f"({', '.join(a.folder for a in existing)}) - `ntc adopt` sets them up for ntc start.")
     plan = Plan()
     try:
         if name is None:

ntc_dev_kit-1.4.0/ntc/workspace/adopt.py

@@ -0,0 +1,316 @@
+"""`ntc adopt`: run existing apps (not made by ntc) with ntc start / setup / clean.
+
+It looks at the folder's subfolders (or the folder itself, when that is an app), works out what
+each one is and how it already runs - its package manager, its dev script and port, its Python
+environment - and writes ntc.toml. Nothing inside the apps is changed: no files written, no env
+overrides, and no `migrate` in setup, since an existing project's .env may point at a shared or
+production database.
+"""
+import glob
+import json
+import os
+import re
+import time
+
+from colorama import Fore, Style
+
+from ntc.utils import prompts
+from ntc.workspace import config
+
+DIM = Fore.LIGHTBLACK_EX
+RESET = Style.RESET_ALL
+
+DEFAULT_PORTS = {"django": 8000, "nextjs": 3000, "vite": 5173, "node": 3000}
+
+
+class Detected:
+    def __init__(self, folder, kind):
+        self.folder = folder            # path relative to the workspace root ("." for the root)
+        self.kind = kind
+        self.name = folder
+        self.port = None
+        self.port_fixed = False         # the dev script sets it: can't move it without editing the app
+        self.manager = "npm"
+        self.script = "dev"
+        self.python = None              # (path, kind, description) for Django
+        self.python_options = []
+        self.notes = []
+
+
+# ── Detection ───────────────────────────────────────────────────────────
+
+def _read_json(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return None
+
+
+def _detect_node(path, folder):
+    package = _read_json(os.path.join(path, "package.json"))
+    if package is None:
+        return None
+    deps = {**package.get("dependencies", {}), **package.get("devDependencies", {})}
+    scripts = package.get("scripts", {})
+    if "next" in deps:
+        kind = "nextjs"
+    elif "vite" in deps:
+        kind = "vite"
+    elif scripts.get("dev") or scripts.get("start"):
+        kind = "node"
+    else:
+        return None  # a library or tooling package, not something to run
+    app = Detected(folder, kind)
+    for lock, manager in (("pnpm-lock.yaml", "pnpm"), ("yarn.lock", "yarn"), ("bun.lockb", "bun"), ("bun.lock", "bun")):
+        if os.path.exists(os.path.join(path, lock)):
+            app.manager = manager
+            break
+    app.script = "dev" if "dev" in scripts else "start"
+    script = scripts.get(app.script, "")
+    match = re.search(r"(?:--port|-p)[ =](\d{2,5})\b", script)
+    if match:
+        app.port, app.port_fixed = int(match.group(1)), True
+    elif kind == "vite":
+        for name in glob.glob(os.path.join(path, "vite.config.*")):
+            try:
+                text = open(name, encoding="utf-8").read()
+            except OSError:
+                continue
+            match = re.search(r"\bport\s*:\s*(\d{2,5})", text)
+            if match:
+                app.port, app.port_fixed = int(match.group(1)), True
+    if app.port is None:
+        app.port = DEFAULT_PORTS[kind]
+    if not os.path.isdir(os.path.join(path, "node_modules")):
+        app.notes.append("dependencies not installed")
+    return app
+
+
+def _conda_envs():
+    """{name: path} of the conda environments on this machine (without running conda)."""
+    import shutil
+    from ntc.templates.drf_structure.main import find_conda_executable
+    home = os.path.expanduser("~")
+    roots = {os.path.join(home, ".conda", "envs")}
+    for base in ("anaconda3", "miniconda3", "miniforge3", "mambaforge"):
+        roots.add(os.path.join(home, base, "envs"))
+        roots.add(os.path.join(os.environ.get("PROGRAMDATA", r"C:\ProgramData"), base, "envs"))
+    for conda in (os.environ.get("CONDA_EXE"), shutil.which(find_conda_executable() or "conda")):
+        if conda:
+            # ...\anaconda3\Scripts\conda.exe, ...\anaconda3\condabin\conda.bat or .../bin/conda
+            roots.add(os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(conda))), "envs"))
+    envs = {}
+    for root in roots:
+        for path in glob.glob(os.path.join(root, "*")):
+            if os.path.isdir(os.path.join(path, "conda-meta")):
+                envs[os.path.basename(path)] = path
+    return envs
+
+
+def _words(text):
+    return {w for w in re.split(r"[^a-z0-9]+", text.lower()) if len(w) > 2} - {"backend", "api", "server", "app", "env"}
+
+
+def _detect_python(path, folder, workspace_name, package):
+    """The candidates for the app's Python, best first: [(path, kind, description)]."""
+    options = []
+    for name in ("env", "venv", ".venv"):
+        candidate = os.path.join(path, name)
+        if os.path.exists(os.path.join(candidate, "pyvenv.cfg")):
+            options.append((name, "venv", f"{name}/ in the app"))
+        elif os.path.isdir(os.path.join(candidate, "conda-meta")):
+            options.append((name, "conda", f"conda env {name}/ in the app"))
+    # A conda environment named after the project (longuo for longuo-backend / longuo_backend).
+    wanted = _words(folder) | _words(workspace_name) | _words(package or "")
+    exact = {folder.lower(), (package or "").lower(), workspace_name.lower()}
+    scored = []
+    for name, env_path in _conda_envs().items():
+        score = 2 if name.lower() in exact else len(_words(name) & wanted)
+        if score:
+            scored.append((score, name, env_path))
+    for _, name, env_path in sorted(scored, reverse=True):
+        options.append((env_path, "conda", f"conda env '{name}'"))
+    for variable, kind in (("VIRTUAL_ENV", "venv"), ("CONDA_PREFIX", "conda")):
+        active = os.environ.get(variable)
+        if active and not any(o[0] == active for o in options):
+            options.append((active, kind, f"the active environment ({os.path.basename(active)})"))
+    options.append(("env", "venv", "a new venv, env/ in the app (`ntc setup` creates it)"))
+    return options
+
+
+def detect_app(path, folder, workspace_name):
+    if os.path.exists(os.path.join(path, "manage.py")):
+        app = Detected(folder, "django")
+        app.port = DEFAULT_PORTS["django"]
+        from ntc.workspace.setup import django_package
+        package = django_package(path)
+        app.package = package
+        app.python_options = _detect_python(path, folder, workspace_name, package)
+        app.python = app.python_options[0]
+        app.requirements = next((r for r in ("requirements-dev.txt", "requirements.txt")
+                                 if os.path.exists(os.path.join(path, r))), None)
+        if app.python[2].startswith("a new venv"):
+            app.notes.append("no Python environment yet")
+        return app
+    if os.path.exists(os.path.join(path, "pubspec.yaml")):
+        app = Detected(folder, "flutter")
+        return app
+    return _detect_node(path, folder)
+
+
+def detect(root):
+    """The apps in root: its subfolders that are apps, or root itself when it is one."""
+    name = os.path.basename(os.path.abspath(root))
+    apps, skipped = [], []
+    for entry in sorted(os.listdir(root)):
+        path = os.path.join(root, entry)
+        if not os.path.isdir(path) or entry.startswith(".") or entry in ("node_modules", "env", "venv"):
+            continue
+        app = detect_app(path, entry, name)
+        (apps.append(app) if app else skipped.append(entry))
+    if not apps:
+        app = detect_app(root, ".", name)
+        if app:
+            app.name = name
+            apps.append(app)
+            skipped = []
+    _short_names(apps)
+    _spread_ports(apps)
+    return apps, skipped
+
+
+def _short_names(apps):
+    """longuo-backend, longuo-crm ... -> backend, crm: the shared prefix says nothing."""
+    names = [a.folder for a in apps if a.folder != "."]
+    if len(names) < 2:
+        return
+    prefix = os.path.commonprefix(names)
+    cut = max(prefix.rfind("-"), prefix.rfind("_"))
+    if cut <= 0:
+        return
+    short = [n[cut + 1:] for n in names]
+    if all(short) and len(set(short)) == len(short):
+        for app in apps:
+            if app.folder != ".":
+                app.name = app.folder[cut + 1:]
+
+
+def _spread_ports(apps):
+    """Two apps on one port can't both run: move the ones whose port isn't fixed by their script."""
+    taken = {a.port for a in apps if a.port and a.port_fixed}
+    for app in sorted(apps, key=lambda a: not a.port_fixed):
+        if not app.port or app.port_fixed:
+            continue
+        port = app.port
+        while port in taken:
+            port += 1
+        if port != app.port:
+            app.notes.append(f"port {app.port} is taken by another app: runs on {port}")
+            app.port = port
+            app.port_moved = True
+        taken.add(port)
+
+
+# ── ntc.toml ────────────────────────────────────────────────────────────
+
+def _run_command(app):
+    manager = app.manager
+    run = f"{manager} run {app.script}" if manager != "npm" or app.script != "start" else "npm start"
+    if getattr(app, "port_moved", False):
+        flag = "--port {port}"
+        run += f" -- {flag}" if manager == "npm" else f" {flag}"
+    return run
+
+
+def entry(app, backend):
+    data = {"kind": app.kind, "path": app.folder}
+    if app.port:
+        data["port"] = app.port
+    if app.kind == "django":
+        python, python_kind, _ = app.python
+        data["python"] = python
+        if python_kind == "conda":
+            data["python_kind"] = "conda"
+        # No `migrate`: an existing project's .env may point at a shared or production database.
+        data["setup"] = [f"{{python}} -m pip install -r {app.requirements}"] if app.requirements else []
+        data["run"] = "{python} manage.py runserver 127.0.0.1:{port}"
+        data["package"] = app.package or "config"  # for the commented worker example only
+        return data
+    if app.kind == "flutter":
+        data["setup"] = ["flutter pub get"]
+        data["run"] = "flutter run"
+        if backend:
+            data["needs"] = [backend]
+        return data
+    if backend:
+        data["needs"] = [backend]
+    install = {"npm": "npm install --no-audit --no-fund", "pnpm": "pnpm install", "yarn": "yarn install",
+               "bun": "bun install"}[app.manager]
+    data["setup"] = [install]
+    data["run"] = _run_command(app)
+    return data
+
+
+def run(path=None, assume_yes=False, dry_run=False):
+    root = os.path.abspath(path or os.getcwd())
+    print(f"\n{Style.BRIGHT}ntc adopt{RESET} {DIM}— {root}{RESET}\n")
+    if os.path.exists(os.path.join(root, config.FILENAME)):
+        prompts.failure(f"{config.FILENAME} already exists here: this is a workspace. `ntc add` adds apps to it.")
+        return False
+    started = time.monotonic()
+    apps, skipped = detect(root)
+    if not apps:
+        prompts.failure("No apps found here (looked for manage.py, package.json with a dev/start script, pubspec.yaml).")
+        return False
+
+    width = max(len(a.name) for a in apps)
+    folder_width = max(len(a.folder) for a in apps)
+    print(f"Found {len(apps)} app{'s' if len(apps) != 1 else ''}:\n")
+    for app in apps:
+        port = f":{app.port}" if app.port else ""
+        extra = app.python[2] if app.kind == "django" else app.manager
+        print(f"  {prompts.CHECK} {Style.BRIGHT}{app.name.ljust(width)}{RESET}  {DIM}{app.folder.ljust(folder_width)}{RESET}  "
+              f"{config.KINDS[app.kind]['label']:<18} {Fore.CYAN}{port:<6}{RESET} {DIM}{extra}{RESET}")
+        for note in app.notes:
+            print(f"      {DIM}· {note}{RESET}")
+    if skipped:
+        print(f"\n  {DIM}Not apps, left out: {', '.join(skipped)}{RESET}")
+    print()
+
+    try:
+        for app in apps:
+            if app.kind == "django" and len(app.python_options) > 1 and not assume_yes:
+                choice = prompts.select(f"Python for {app.name}", [
+                    (description, i, "") for i, (_, _, description) in enumerate(app.python_options)])
+                app.python = app.python_options[choice]
+        if dry_run:
+            prompts.info("Dry run - nothing was written.")
+            return True
+        if not assume_yes and not prompts.confirm(f"Write {config.FILENAME}? (nothing in the apps changes)", default=True):
+            prompts.info("Nothing was written.")
+            return True
+    except prompts.Cancelled:
+        print(f"\n{DIM}Nothing was written.{RESET}")
+        return True
+
+    backend = next((a.name for a in apps if a.kind == "django"), None)
+    entries = {app.name: entry(app, backend) for app in apps}
+    name = os.path.basename(root)
+    config.write(root, name, entries)
+    has_root_git = os.path.isdir(os.path.join(root, ".git"))
+    git = "single" if has_root_git else ("per-app" if all(
+        os.path.isdir(os.path.join(root, a.folder, ".git")) for a in apps) else "none")
+    from ntc.workspace.create import _set_top_level
+    _set_top_level(root, "git", git)
+    prompts.success(f"{config.FILENAME} written {DIM}({time.monotonic() - started:.1f}s) - edit it to change a port or a command{RESET}")
+
+    needs_setup = [a.name for a in apps if a.notes and any("not installed" in n or "no Python" in n for n in a.notes)]
+    print(f"\n{Style.BRIGHT}Next:{RESET}")
+    if needs_setup:
+        print(f"  {Fore.CYAN}ntc setup{RESET}   {DIM}# installs {', '.join(needs_setup)}{RESET}")
+    print(f"  {Fore.CYAN}ntc start{RESET}\n")
+    if backend:
+        prompts.info(f"{backend}: setup installs its packages but doesn't migrate - run migrations yourself "
+                     f"when its .env points where you expect.")
+    return True