lame-project-cli 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,55 @@
1
+ Metadata-Version: 2.4
2
+ Name: lame-project-cli
3
+ Version: 1.1.0
4
+ Summary: Python client library and local-first CLI for Lame cloud projects
5
+ Classifier: Programming Language :: Python :: 3
6
+ Classifier: Programming Language :: Python :: 3 :: Only
7
+ Classifier: Operating System :: OS Independent
8
+ Requires-Python: >=3.9
9
+ Description-Content-Type: text/markdown
10
+
11
+ # Lame Python client
12
+
13
+ The `lame` package is a typed, standard-library Python client for the Lame
14
+ project API. It is included in the `lame-project-cli` distribution.
15
+
16
+ Install from a source checkout with:
17
+
18
+ ```console
19
+ python -m pip install .
20
+ ```
21
+
22
+ Once the distribution is published to PyPI, install it with:
23
+
24
+ ```console
25
+ python -m pip install lame-project-cli
26
+ ```
27
+
28
+ Generate a short-lived CLI token from the signed-in Projects page and keep it
29
+ private:
30
+
31
+ ```python
32
+ from lame import LameClient
33
+
34
+ client = LameClient("https://your-lame-server.example", token="YOUR_TOKEN")
35
+ projects = client.list_projects()
36
+ project = client.create_project("research-notes")
37
+ client.rename_project(project.id, "research")
38
+ ```
39
+
40
+ `LameClient` also provides `storage_connections()`, `delete_project(id)`,
41
+ `push_archive(id, bytes_or_file)`, and `pull_archive(id)`. The server validates
42
+ archive paths and size limits and syncs files to the storage connection assigned
43
+ to the project. The client does not execute project code.
44
+
45
+ Use the `lame` command-line entry point for local project sync:
46
+
47
+ ```console
48
+ lame login
49
+ lame projects
50
+ lame push research
51
+ lame pull research --path .\research
52
+ ```
53
+
54
+ The token is a bearer credential. Do not hard-code it or include it in source
55
+ control, and revoke it from Projects when it is no longer needed.
@@ -0,0 +1,44 @@
1
+ # Lame - The utopia of huggingface.co
2
+ ### About
3
+ - *Lame* is a website which is used to train/run AI models by connecting the runtime to a google or kaggle runtime via API keys.
4
+ - *Lame* can combine multiple runtime keys to train AI models. This API key can also be exported to run AI models on local computers or somethin like that.
5
+ - *Lame* is a website which stores all sorts of datasets / modelsn on GoogleDrive, OneDrive, TerraBox, etc.
6
+
7
+ ### Sign-in setup
8
+ - The Flask entry point is `server/sever.py`. Database setup and request helpers live in `server/db.py`, sign-in/OAuth/OTP flows in `server/auth.py`, and linked sign-in management in `server/accounts.py`.
9
+ - Install the project dependencies with `python -m pip install -r requirements.txt`.
10
+ - The website UI is built with React and Tailwind CSS. Frontend source and build configuration live in `templates/frontend/`. To rebuild its production assets after changing the frontend, run `cd templates/frontend`, `npm.cmd ci`, then `npm.cmd run build` on Windows (use `npm ci` on other platforms). Vite writes the assets to `templates/react/`, which Flask serves directly; Node is not required just to run the prebuilt app.
11
+ - Put Google OAuth settings and `FLASK_SECRET_KEY` in `secrets/.env.google`. Put mail-server settings in `secrets/.env.smtp`. The server loads both files on startup; operating-system environment variables take precedence.
12
+ - To enable Google sign-in, create a Google OAuth client for a web application. Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `secrets/.env.google`, and add the exact site URLs ending in `/login/google/callback` and `/runtime/colab/callback` as authorized redirect URIs (for local development, `http://127.0.0.1:5000/login/google/callback` and `http://127.0.0.1:5000/runtime/colab/callback`). Normal sign-in and linking additional accounts use the first callback; managed Colab runtime authorization uses the second. To use the standalone `auth.py` sign-in flow, also register `http://127.0.0.1:8765/callback` or set `GOOGLE_AUTH_REDIRECT_URI` to another registered localhost callback. Signed-in users can open **Account** and connect additional Google identities to their existing Lame account; those identities share the same workspace and do not merge separate Lame accounts.
13
+ - Configure SMTP to send verification and password-reset links in `secrets/.env.smtp`. Set `SMTP_HOST`, `SMTP_PORT`, and `SMTP_FROM_EMAIL`; if your provider requires authentication, also set `SMTP_USERNAME` and `SMTP_PASSWORD`. By default the app uses STARTTLS (usually port `587`). Set `SMTP_USE_SSL=true` for implicit TLS (usually port `465`). Do not commit credentials to source control.
14
+ - New email/password accounts must verify their email before logging in. Passwords must be at least 12 characters and include an uppercase letter, a lowercase letter, a number, and a symbol. Registration also confirms the password and checks username availability; usernames are unique regardless of capitalization.
15
+ - The login page supports one-hour email-verification and password-reset links. Reset requests only send to verified accounts, and return a generic response to avoid revealing which addresses are registered. Signed-in users can add additional email sign-ins from **Account** by verifying a six-digit OTP sent through the configured SMTP server; those addresses can also sign in by requesting a one-time email code. Codes expire after 10 minutes, can be resent once per minute, allow at most five attempts, and are limited to 10 requests per IP address per hour.
16
+ - The **Account** page lets users label Google sign-ins and remove Google or OTP-email sign-ins. It prevents removing the last configured sign-in method.
17
+ - Existing username/password accounts remain supported; their password is upgraded to a hash when they next log in. Google accounts with an email matching an existing account are linked after Google verifies that email.
18
+ - `server/api/colab/src/auth.py` signs in to Google directly using OAuth authorization code flow with PKCE; it does not invoke Colab CLI or create a Colab runtime. For this standalone flow, configure `GOOGLE_AUTH_REDIRECT_URI` and register that exact localhost redirect URI with the OAuth client.
19
+ - Fill in the values in `secrets/.env.google` and `secrets/.env.smtp`, then restart the app with `.\run.bat` on Windows. Set `FLASK_SECRET_KEY` to a long, random secret. The app generates a temporary key if it is left blank, so sessions will expire after a restart.
20
+
21
+ ### Python editor and terminal
22
+ - Signed-in users can open **Python editor** or **Linux terminal** from the React and Tailwind UI. The editor uses Monaco with Python completion suggestions, an integrated Bash terminal, a resizable Explorer/sidebar and bottom panel, and per-user folders for saved `.py` files (up to 5 MB per file).
23
+ - **Projects** stores private project folders in the selected rclone remote. Install rclone on the Lame server and ensure `rclone` is on `PATH`; alternatively, set `RCLONE_BINARY` to the executable path. In Projects, add multiple named connections from your `rclone.conf`, choose a default, and select a connection for each new project. Project creation saves metadata immediately; the cloud folder is created on the first file write or sync rather than making you wait for an rclone request. Existing projects are migrated to their original default connection. Config contents are encrypted in the local database with `FLASK_SECRET_KEY`, so keep that key stable and private. Connections with projects assigned cannot be removed; deleting a project permanently purges its files from its assigned remote.
24
+ - For the fast local-first workflow, install the CLI from the project root with `python -m pip install .`. In **Projects**, generate a one-day CLI token, then run `lame login` and paste it at the prompt. From a local folder use `lame projects`, `lame create my-project`, `lame push my-project`, and `lame pull my-project --path .\my-project`. `push` uploads a single ZIP archive and the server copies its extracted files to rclone in one operation; it does not delete cloud files missing from your local folder. `pull` will only write into an empty folder unless you pass `--force`. Use `.lameignore` for additional ignored paths. By default the CLI skips Git metadata, virtual environments, caches, `node_modules`, common OS files, private `.env` files, keys, and symlinks. CLI archives are limited to 128 MB compressed, 512 MB unpacked, 10,000 files, and 128 MB per file.
25
+ - The local folder is your working copy, but `push` sends its archive over HTTPS through the Lame API to the server, which uploads it to the connected rclone remote. The server extracts into a temporary directory and removes it after the sync. Use a short-lived CLI token, revoke it from Projects when finished, and do not include credentials in a project.
26
+ - The same installable distribution also provides the importable `lame` Python package. Install from this checkout with `python -m pip install .` (or use `python -m pip install lame-project-cli` after publishing the distribution to PyPI), then use `from lame import LameClient`; pass a short-lived token generated from Projects to `LameClient(server, token)`. The client supports project listing/creation/renaming/deletion and ZIP archive push/pull. It uses Python's standard library and is typed.
27
+ - The existing browser **Python editor** remains available for quick edits of cloud files; its individual file operations still access the cloud API. Use the CLI for bulk/local project work and the browser editor for convenience. **Run** stays gated on a connected runtime and project-storage provider.
28
+ - The project API is implemented in Flask by default. To use the optional PHP project API, install PHP 8.1 or later with the PDO SQLite and OpenSSL extensions enabled, then start a local PHP server from the project root: `php -S 127.0.0.1:8765 -t templates/php templates/php/router.php`. In the Flask server's environment, set `PHP_PROJECT_API_URL=http://127.0.0.1:8765` before running `.\run.bat`. Keep the PHP server bound to localhost: Flask authenticates the user, checks CSRF tokens, and signs each proxied request; the PHP API rejects unsigned requests. Both processes must use the same stable `FLASK_SECRET_KEY` and be able to access the same `db/users.db` and rclone executable. Without `PHP_PROJECT_API_URL`, the existing Flask project API remains active.
29
+ - Use **Open file** in the browser editor to preview a local Python file. Files over 5 MB show a size warning; compiled formats (such as `.pyc`, `.pyd`, `.dll`, or `.exe`) show a separate message that there is no built-in editor support.
30
+ - The Run button is enabled only when both a runtime and an rclone project-storage provider are connected. Python code runs on the connected runtime; it is never run by the browser or the Lame server. Monaco loads from a CDN, so the editor needs internet access on first load.
31
+ - The standalone and integrated terminals are Bash shells on the connected Colab or Jupyter runtime. Enter Linux commands directly, for example `nvidia-smi`, `df -h`, or `pwd`; runtime shortcuts include `storage-info`, `memory-info`, `gpu-info`, and `python-version`. Use `help` for a reminder and `clear` to clear the display. A connected runtime is required. Commands run on that runtime, never on the Lame web server.
32
+
33
+ ### Connect a tunneled Jupyter runtime
34
+ - Install updated dependencies with `python -m pip install -r requirements.txt`, and set a stable, random `FLASK_SECRET_KEY`. Runtime tokens are encrypted using this key, so changing it makes saved runtime connections unreadable; users can reconnect after a key change.
35
+ - In a Colab notebook, install/start a Jupyter Server in the Colab VM with a token and expose its port (8888) through an HTTPS tunnel such as Cloudflare Tunnel or ngrok. The tunnel must forward WebSocket traffic as well as HTTP. The server needs outbound access to the tunnel provider and must remain running while Lame is connected.
36
+ - Example Colab setup (run in a notebook cell): install `jupyter-server` and `ipykernel`, create a long random token, launch `jupyter server --ip=0.0.0.0 --port=8888 --ServerApp.open_browser=False --IdentityProvider.token=<token>` in the background, then start a Cloudflare quick tunnel with `cloudflared tunnel --url http://127.0.0.1:8888`. Read the generated `https://….trycloudflare.com` URL from cloudflared’s output and enter it with the token in Lame. Install the Cloudflare `cloudflared` binary in the Colab VM first. Keep the cell/runtime alive; restarting the runtime changes the tunnel URL and token.
37
+ - In Lame’s editor, choose **Connect runtime**, paste the HTTPS tunnel URL and Jupyter token, then use **Run** or enter commands in either Bash terminal. Lame creates a Jupyter kernel for each request, executes Python editor code as Python and terminal commands as Bash, returns output, and shuts that kernel down. This uses Colab compute but does not attach to the notebook UI’s existing kernel or preserve Python variables between editor runs.
38
+ - The runtime endpoint accepts public HTTPS tunnel domains only (`trycloudflare.com`, `ngrok-free.app`, `ngrok.io`, and `loca.lt`) and checks that they resolve to public IP addresses. Do not expose an unauthenticated Jupyter server. Disconnect from the editor to remove the saved encrypted token.
39
+ - The tunneled Jupyter connection remains available as an alternative to managed runtime provisioning. Google’s [Colab FAQ](https://research.google.com/colaboratory/faq.html) says free managed runtimes may be terminated when primarily accessed through another web UI; use a Colab plan that permits the workflow or compute you control.
40
+
41
+ ### Managed Colab runtime
42
+ - The editor can request a personal Colab runtime with the Colab CLI-style workflow: authorize Google once, choose CPU or GPU, allocate a runtime, execute against its kernel, and stop it to release the allocation.
43
+ - Authorization requests the `colaboratory` and Cloud Platform OAuth scopes and stores only an encrypted refresh credential in Lame’s local database. It is separate from the normal Google sign-in used to link accounts.
44
+ - The managed runtime is based on Google’s public Colab runtime assignment protocol, not copied from or bundled with the Colab CLI. CPU/GPU availability and compute-unit balance are controlled by Google. A positive compute-unit balance may be required for a separate web UI to remain usable.
@@ -0,0 +1,45 @@
1
+ # Lame Python client
2
+
3
+ The `lame` package is a typed, standard-library Python client for the Lame
4
+ project API. It is included in the `lame-project-cli` distribution.
5
+
6
+ Install from a source checkout with:
7
+
8
+ ```console
9
+ python -m pip install .
10
+ ```
11
+
12
+ Once the distribution is published to PyPI, install it with:
13
+
14
+ ```console
15
+ python -m pip install lame-project-cli
16
+ ```
17
+
18
+ Generate a short-lived CLI token from the signed-in Projects page and keep it
19
+ private:
20
+
21
+ ```python
22
+ from lame import LameClient
23
+
24
+ client = LameClient("https://your-lame-server.example", token="YOUR_TOKEN")
25
+ projects = client.list_projects()
26
+ project = client.create_project("research-notes")
27
+ client.rename_project(project.id, "research")
28
+ ```
29
+
30
+ `LameClient` also provides `storage_connections()`, `delete_project(id)`,
31
+ `push_archive(id, bytes_or_file)`, and `pull_archive(id)`. The server validates
32
+ archive paths and size limits and syncs files to the storage connection assigned
33
+ to the project. The client does not execute project code.
34
+
35
+ Use the `lame` command-line entry point for local project sync:
36
+
37
+ ```console
38
+ lame login
39
+ lame projects
40
+ lame push research
41
+ lame pull research --path .\research
42
+ ```
43
+
44
+ The token is a bearer credential. Do not hard-code it or include it in source
45
+ control, and revoke it from Projects when it is no longer needed.
@@ -0,0 +1,6 @@
1
+ """Python client library for the Lame project workspace."""
2
+
3
+ from .client import LameClient, LameError, Project
4
+
5
+ __all__ = ['LameClient', 'LameError', 'Project']
6
+ __version__ = '1.1.0'
@@ -0,0 +1,172 @@
1
+ """Small standard-library client for the Lame project API."""
2
+
3
+ import json
4
+ import urllib.error
5
+ import urllib.request
6
+ from dataclasses import dataclass
7
+ from typing import Any, BinaryIO, Dict, List, Optional, Union
8
+ from urllib.parse import urlsplit
9
+
10
+
11
+ class LameError(RuntimeError):
12
+ """Raised when a Lame API request fails."""
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class Project:
17
+ """A project visible to the authenticated user."""
18
+
19
+ id: int
20
+ name: str
21
+ storage_provider_id: Optional[int] = None
22
+ storage_name: Optional[str] = None
23
+ created_at: Optional[str] = None
24
+ updated_at: Optional[str] = None
25
+
26
+ @classmethod
27
+ def from_dict(cls, value: Dict[str, Any]) -> 'Project':
28
+ return cls(
29
+ id=value['id'],
30
+ name=value['name'],
31
+ storage_provider_id=value.get('storage_provider_id'),
32
+ storage_name=value.get('storage_name'),
33
+ created_at=value.get('created_at'),
34
+ updated_at=value.get('updated_at'),
35
+ )
36
+
37
+
38
+ class LameClient:
39
+ """Make authenticated requests to a Lame server.
40
+
41
+ Generate a CLI token from the signed-in Projects page and pass it as
42
+ ``token``. Keep that token private and revoke it when it is no longer needed.
43
+ """
44
+
45
+ def __init__(self, server: str, token: str, timeout: Union[int, float] = 600) -> None:
46
+ if not isinstance(server, str) or not server.strip():
47
+ raise ValueError('server must be a non-empty URL')
48
+ if not isinstance(token, str) or not token.strip():
49
+ raise ValueError('token must be a non-empty string')
50
+ parsed_server = urlsplit(server)
51
+ if (
52
+ parsed_server.scheme not in {'http', 'https'}
53
+ or not parsed_server.hostname
54
+ or parsed_server.username
55
+ or parsed_server.password
56
+ or parsed_server.query
57
+ or parsed_server.fragment
58
+ ):
59
+ raise ValueError('server must be an HTTP(S) URL without credentials or query parameters')
60
+ if parsed_server.scheme == 'http' and parsed_server.hostname.lower() not in {
61
+ 'localhost',
62
+ '127.0.0.1',
63
+ '::1',
64
+ }:
65
+ raise ValueError('use HTTPS when connecting to a non-local Lame server')
66
+ if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
67
+ raise ValueError('timeout must be a positive number')
68
+ self.server = server.rstrip('/')
69
+ self.token = token
70
+ self.timeout = timeout
71
+
72
+ def _request(
73
+ self,
74
+ path: str,
75
+ method: str = 'GET',
76
+ payload: Optional[Dict[str, Any]] = None,
77
+ raw: Optional[bytes] = None,
78
+ content_type: Optional[str] = None,
79
+ download: bool = False,
80
+ ) -> Any:
81
+ headers = {'Authorization': f'Bearer {self.token}'}
82
+ body = raw
83
+ if payload is not None:
84
+ body = json.dumps(payload).encode('utf-8')
85
+ headers['Content-Type'] = 'application/json'
86
+ elif content_type:
87
+ headers['Content-Type'] = content_type
88
+ request = urllib.request.Request(
89
+ f'{self.server}{path}',
90
+ data=body,
91
+ headers=headers,
92
+ method=method,
93
+ )
94
+ try:
95
+ with urllib.request.urlopen(request, timeout=self.timeout) as response:
96
+ result = response.read()
97
+ except urllib.error.HTTPError as error:
98
+ response_body = error.read()
99
+ try:
100
+ details = json.loads(response_body.decode('utf-8'))
101
+ message = details.get('error', f'Request failed with HTTP {error.code}.')
102
+ except (UnicodeDecodeError, json.JSONDecodeError, AttributeError):
103
+ message = f'Request failed with HTTP {error.code}.'
104
+ raise LameError(message) from error
105
+ except (urllib.error.URLError, TimeoutError, OSError) as error:
106
+ reason = getattr(error, 'reason', error)
107
+ raise LameError(f'Could not reach the Lame server: {reason}') from error
108
+ if download:
109
+ return result
110
+ try:
111
+ return json.loads(result.decode('utf-8')) if result else {}
112
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
113
+ raise LameError('The Lame server returned an invalid response.') from error
114
+
115
+ def list_projects(self) -> List[Project]:
116
+ """Return the user's projects as :class:`Project` instances."""
117
+ response = self._request('/api/projects')
118
+ return [Project.from_dict(item) for item in response.get('projects', [])]
119
+
120
+ def storage_connections(self) -> List[Dict[str, Any]]:
121
+ """Return the user's configured project storage connections."""
122
+ response = self._request('/api/projects/storage')
123
+ return response.get('providers', [])
124
+
125
+ def create_project(self, name: str, storage_provider_id: Optional[int] = None) -> Project:
126
+ """Create a project in the default or explicitly selected connection."""
127
+ payload = {'name': name}
128
+ if storage_provider_id is not None:
129
+ payload['storage_provider_id'] = storage_provider_id
130
+ response = self._request('/api/projects', method='POST', payload=payload)
131
+ return Project.from_dict(response)
132
+
133
+ def rename_project(self, project_id: int, name: str) -> Project:
134
+ """Rename a project without moving its cloud files."""
135
+ response = self._request(
136
+ f'/api/projects/{int(project_id)}',
137
+ method='PATCH',
138
+ payload={'name': name},
139
+ )
140
+ return Project.from_dict(response)
141
+
142
+ def delete_project(self, project_id: int) -> Dict[str, Any]:
143
+ """Delete a project and its files from its configured cloud remote."""
144
+ return self._request(f'/api/projects/{int(project_id)}', method='DELETE')
145
+
146
+ def push_archive(
147
+ self,
148
+ project_id: int,
149
+ archive: Union[bytes, BinaryIO],
150
+ ) -> Dict[str, Any]:
151
+ """Upload a ZIP archive to a project.
152
+
153
+ ``archive`` may be bytes or a binary file object. The archive is sent
154
+ directly to the Lame server; the server applies its configured size and
155
+ path validation before syncing files to cloud storage.
156
+ """
157
+ archive_bytes = archive.read() if hasattr(archive, 'read') else archive
158
+ if not isinstance(archive_bytes, bytes):
159
+ raise TypeError('archive must be bytes or a binary file object')
160
+ return self._request(
161
+ f'/api/projects/{int(project_id)}/archive',
162
+ method='POST',
163
+ raw=archive_bytes,
164
+ content_type='application/zip',
165
+ )
166
+
167
+ def pull_archive(self, project_id: int) -> bytes:
168
+ """Download a project's ZIP archive as bytes."""
169
+ return self._request(
170
+ f'/api/projects/{int(project_id)}/archive',
171
+ download=True,
172
+ )
File without changes
@@ -0,0 +1,55 @@
1
+ Metadata-Version: 2.4
2
+ Name: lame-project-cli
3
+ Version: 1.1.0
4
+ Summary: Python client library and local-first CLI for Lame cloud projects
5
+ Classifier: Programming Language :: Python :: 3
6
+ Classifier: Programming Language :: Python :: 3 :: Only
7
+ Classifier: Operating System :: OS Independent
8
+ Requires-Python: >=3.9
9
+ Description-Content-Type: text/markdown
10
+
11
+ # Lame Python client
12
+
13
+ The `lame` package is a typed, standard-library Python client for the Lame
14
+ project API. It is included in the `lame-project-cli` distribution.
15
+
16
+ Install from a source checkout with:
17
+
18
+ ```console
19
+ python -m pip install .
20
+ ```
21
+
22
+ Once the distribution is published to PyPI, install it with:
23
+
24
+ ```console
25
+ python -m pip install lame-project-cli
26
+ ```
27
+
28
+ Generate a short-lived CLI token from the signed-in Projects page and keep it
29
+ private:
30
+
31
+ ```python
32
+ from lame import LameClient
33
+
34
+ client = LameClient("https://your-lame-server.example", token="YOUR_TOKEN")
35
+ projects = client.list_projects()
36
+ project = client.create_project("research-notes")
37
+ client.rename_project(project.id, "research")
38
+ ```
39
+
40
+ `LameClient` also provides `storage_connections()`, `delete_project(id)`,
41
+ `push_archive(id, bytes_or_file)`, and `pull_archive(id)`. The server validates
42
+ archive paths and size limits and syncs files to the storage connection assigned
43
+ to the project. The client does not execute project code.
44
+
45
+ Use the `lame` command-line entry point for local project sync:
46
+
47
+ ```console
48
+ lame login
49
+ lame projects
50
+ lame push research
51
+ lame pull research --path .\research
52
+ ```
53
+
54
+ The token is a bearer credential. Do not hard-code it or include it in source
55
+ control, and revoke it from Projects when it is no longer needed.
@@ -0,0 +1,13 @@
1
+ README.md
2
+ pyproject.toml
3
+ lame/README.md
4
+ lame/__init__.py
5
+ lame/client.py
6
+ lame/py.typed
7
+ lame_project_cli.egg-info/PKG-INFO
8
+ lame_project_cli.egg-info/SOURCES.txt
9
+ lame_project_cli.egg-info/dependency_links.txt
10
+ lame_project_cli.egg-info/entry_points.txt
11
+ lame_project_cli.egg-info/top_level.txt
12
+ tools/__init__.py
13
+ tools/lame_cli.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ lame = tools.lame_cli:main
@@ -0,0 +1,24 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "lame-project-cli"
7
+ version = "1.1.0"
8
+ description = "Python client library and local-first CLI for Lame cloud projects"
9
+ readme = "lame/README.md"
10
+ requires-python = ">=3.9"
11
+ classifiers = [
12
+ "Programming Language :: Python :: 3",
13
+ "Programming Language :: Python :: 3 :: Only",
14
+ "Operating System :: OS Independent",
15
+ ]
16
+
17
+ [project.scripts]
18
+ lame = "tools.lame_cli:main"
19
+
20
+ [tool.setuptools]
21
+ packages = ["lame", "tools"]
22
+
23
+ [tool.setuptools.package-data]
24
+ lame = ["py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ """Command-line tools for Lame."""
@@ -0,0 +1,429 @@
1
+ #!/usr/bin/env python3
2
+ """Local-first command-line sync for Lame cloud projects."""
3
+
4
+ import argparse
5
+ import fnmatch
6
+ import getpass
7
+ import io
8
+ import json
9
+ import os
10
+ import re
11
+ import shutil
12
+ import stat
13
+ import sys
14
+ import tempfile
15
+ import urllib.error
16
+ import urllib.request
17
+ import zipfile
18
+ from pathlib import Path
19
+
20
+ MAX_ARCHIVE_BYTES = 128 * 1024 * 1024
21
+ MAX_FILE_BYTES = 128 * 1024 * 1024
22
+ DEFAULT_SERVER = 'http://127.0.0.1:5000'
23
+ IGNORED_DIRECTORIES = {
24
+ '.git',
25
+ '.lame',
26
+ '.venv',
27
+ 'venv',
28
+ 'node_modules',
29
+ '__pycache__',
30
+ '.pytest_cache',
31
+ '.mypy_cache',
32
+ '.ruff_cache',
33
+ '.aws',
34
+ '.ssh',
35
+ 'secrets',
36
+ 'credentials',
37
+ }
38
+ IGNORED_FILES = {
39
+ '.ds_store',
40
+ 'thumbs.db',
41
+ 'desktop.ini',
42
+ 'id_rsa',
43
+ 'id_ed25519',
44
+ 'credentials.json',
45
+ }
46
+ VALID_PATH_PART = re.compile(r'^[A-Za-z0-9._ -][A-Za-z0-9_. -]{0,99}$')
47
+
48
+
49
+ class LameCliError(Exception):
50
+ """A user-facing CLI error."""
51
+
52
+
53
+ def config_path():
54
+ if os.name == 'nt':
55
+ base = Path(os.environ.get('APPDATA', Path.home() / 'AppData' / 'Roaming'))
56
+ return base / 'Lame' / 'cli.json'
57
+ return Path(os.environ.get('XDG_CONFIG_HOME', Path.home() / '.config')) / 'lame' / 'cli.json'
58
+
59
+
60
+ def read_config():
61
+ path = config_path()
62
+ try:
63
+ value = json.loads(path.read_text(encoding='utf-8'))
64
+ except FileNotFoundError:
65
+ raise LameCliError('You are not logged in. Run `lame login` first.')
66
+ except (OSError, json.JSONDecodeError) as error:
67
+ raise LameCliError(f'Could not read CLI credentials at {path}: {error}') from error
68
+ if not isinstance(value, dict) or not value.get('server') or not value.get('token'):
69
+ raise LameCliError('The saved CLI credentials are incomplete. Run `lame login` again.')
70
+ return value
71
+
72
+
73
+ def write_config(server, token):
74
+ path = config_path()
75
+ try:
76
+ path.parent.mkdir(parents=True, exist_ok=True)
77
+ path.write_text(
78
+ json.dumps({'server': server.rstrip('/'), 'token': token}, indent=2) + '\n',
79
+ encoding='utf-8',
80
+ )
81
+ try:
82
+ path.chmod(stat.S_IRUSR | stat.S_IWUSR)
83
+ except OSError:
84
+ if os.name != 'nt':
85
+ raise
86
+ except OSError as error:
87
+ raise LameCliError(f'Could not save CLI credentials at {path}: {error}') from error
88
+
89
+
90
+ def remove_temporary_directory(path):
91
+ try:
92
+ shutil.rmtree(path)
93
+ except FileNotFoundError:
94
+ pass
95
+ except OSError as error:
96
+ print(f'Warning: could not remove temporary sync files at {path}: {error}', file=sys.stderr)
97
+
98
+
99
+ def api_request(path, method='GET', payload=None, raw=None, content_type=None, download=False):
100
+ config = read_config()
101
+ headers = {'Authorization': f'Bearer {config["token"]}'}
102
+ body = raw
103
+ if payload is not None:
104
+ body = json.dumps(payload).encode('utf-8')
105
+ headers['Content-Type'] = 'application/json'
106
+ elif content_type:
107
+ headers['Content-Type'] = content_type
108
+ request = urllib.request.Request(
109
+ config['server'] + path,
110
+ data=body,
111
+ headers=headers,
112
+ method=method,
113
+ )
114
+ try:
115
+ with urllib.request.urlopen(request, timeout=600) as response:
116
+ result = response.read()
117
+ except urllib.error.HTTPError as error:
118
+ response_body = error.read()
119
+ try:
120
+ details = json.loads(response_body.decode('utf-8'))
121
+ message = details.get('error', f'Request failed with HTTP {error.code}.')
122
+ except (UnicodeDecodeError, json.JSONDecodeError, AttributeError):
123
+ message = f'Request failed with HTTP {error.code}.'
124
+ if error.code == 401:
125
+ message += ' Your CLI token may have expired; generate a new one in Projects.'
126
+ raise LameCliError(message) from error
127
+ except (urllib.error.URLError, TimeoutError, OSError) as error:
128
+ reason = getattr(error, 'reason', error)
129
+ raise LameCliError(f'Could not reach the Lame server: {reason}') from error
130
+ if download:
131
+ return result
132
+ try:
133
+ return json.loads(result.decode('utf-8')) if result else {}
134
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
135
+ raise LameCliError('The Lame server returned an invalid response.') from error
136
+
137
+
138
+ def project_for(value):
139
+ result = api_request('/api/projects')
140
+ projects = result.get('projects', [])
141
+ for project in projects:
142
+ if str(project.get('id')) == value or project.get('name', '').casefold() == value.casefold():
143
+ return project
144
+ names = ', '.join(f'{item["name"]} (ID {item["id"]})' for item in projects)
145
+ raise LameCliError(f'Project {value!r} was not found. Available projects: {names or "none"}')
146
+
147
+
148
+ def ignore_rules(root):
149
+ path = root / '.lameignore'
150
+ try:
151
+ lines = path.read_text(encoding='utf-8').splitlines()
152
+ except FileNotFoundError:
153
+ return []
154
+ except OSError as error:
155
+ raise LameCliError(f'Could not read {path}: {error}') from error
156
+ return [
157
+ line.strip()
158
+ for line in lines
159
+ if line.strip() and not line.lstrip().startswith('#')
160
+ ]
161
+
162
+
163
+ def ignored(relative_path, rules):
164
+ parts = relative_path.parts
165
+ if any(part in IGNORED_DIRECTORIES for part in parts):
166
+ return True
167
+ name = parts[-1].lower()
168
+ if (
169
+ name in IGNORED_FILES
170
+ or name.endswith(('.pyc', '.pyo', '.pyd', '.pem', '.key', '.p12'))
171
+ or name == '.env'
172
+ or name.startswith('.env.')
173
+ or name.endswith('.env')
174
+ or 'service-account' in name and name.endswith('.json')
175
+ ):
176
+ return True
177
+ path_text = relative_path.as_posix()
178
+ result = False
179
+ for rule in rules:
180
+ negate = rule.startswith('!')
181
+ pattern = rule[1:] if negate else rule
182
+ pattern = pattern.lstrip('/')
183
+ if not pattern:
184
+ continue
185
+ matches = (
186
+ fnmatch.fnmatch(path_text, pattern)
187
+ or path_text == pattern.rstrip('/')
188
+ or path_text.startswith(pattern.rstrip('/') + '/')
189
+ )
190
+ if matches:
191
+ result = not negate
192
+ return result
193
+
194
+
195
+ def build_archive(root):
196
+ root = root.resolve()
197
+ if not root.is_dir():
198
+ raise LameCliError(f'Project folder does not exist: {root}')
199
+ rules = ignore_rules(root)
200
+ temporary = Path(tempfile.mkdtemp(prefix='lame-sync-'))
201
+ archive_path = temporary / 'project.zip'
202
+ files = 0
203
+ skipped = 0
204
+ succeeded = False
205
+ try:
206
+ with zipfile.ZipFile(archive_path, 'w', compression=zipfile.ZIP_DEFLATED) as archive:
207
+ for directory, directories, filenames in os.walk(root, followlinks=False):
208
+ current = Path(directory)
209
+ relative_directory = current.relative_to(root)
210
+ directories[:] = [
211
+ name for name in directories
212
+ if not ignored(relative_directory / name, rules)
213
+ and not (current / name).is_symlink()
214
+ ]
215
+ for filename in filenames:
216
+ file_path = current / filename
217
+ relative_path = file_path.relative_to(root)
218
+ if ignored(relative_path, rules) or file_path.is_symlink():
219
+ skipped += 1
220
+ continue
221
+ if (
222
+ len(relative_path.parts) > 10
223
+ or any(not VALID_PATH_PART.fullmatch(part) for part in relative_path.parts)
224
+ ):
225
+ raise LameCliError(
226
+ f'{relative_path.as_posix()} has a path component unsupported by project sync.'
227
+ )
228
+ size = file_path.stat().st_size
229
+ if size > MAX_FILE_BYTES:
230
+ skipped += 1
231
+ continue
232
+ archive.write(file_path, relative_path.as_posix())
233
+ files += 1
234
+ size = archive_path.stat().st_size
235
+ if size > MAX_ARCHIVE_BYTES:
236
+ raise LameCliError('The compressed project is larger than the 128 MB CLI sync limit.')
237
+ succeeded = True
238
+ return archive_path, files, skipped, size
239
+ except OSError as error:
240
+ raise LameCliError(f'Could not create the local project archive: {error}') from error
241
+ finally:
242
+ if not succeeded:
243
+ remove_temporary_directory(temporary)
244
+
245
+
246
+ def command_login(args):
247
+ server = args.server.rstrip('/')
248
+ if not server.startswith(('http://', 'https://')):
249
+ raise LameCliError('Enter a server URL beginning with http:// or https://.')
250
+ token = getpass.getpass('Paste the short-lived CLI token from Lame Projects: ').strip()
251
+ if not token:
252
+ raise LameCliError('A CLI token is required.')
253
+ write_config(server, token)
254
+ try:
255
+ response = api_request('/api/projects')
256
+ except LameCliError:
257
+ try:
258
+ config_path().unlink(missing_ok=True)
259
+ except OSError as cleanup_error:
260
+ print(f'Warning: could not remove rejected CLI credentials: {cleanup_error}', file=sys.stderr)
261
+ raise
262
+ print(f'Logged in to {server}. {len(response.get("projects", []))} project(s) available.')
263
+
264
+
265
+ def command_logout(_args):
266
+ path = config_path()
267
+ try:
268
+ read_config()
269
+ api_request('/api/cli/token', method='DELETE')
270
+ except LameCliError as error:
271
+ if 'not logged in' not in str(error):
272
+ print(f'Warning: {error}', file=sys.stderr)
273
+ try:
274
+ path.unlink(missing_ok=True)
275
+ except OSError as error:
276
+ raise LameCliError(f'Could not remove local credentials at {path}: {error}') from error
277
+ print('Logged out and removed local CLI credentials.')
278
+
279
+
280
+ def command_projects(_args):
281
+ projects = api_request('/api/projects').get('projects', [])
282
+ if not projects:
283
+ print('No projects yet. Create one in Lame Projects or run `create <name>`.')
284
+ return
285
+ print(f'{"ID":<8} {"PROJECT":<32} UPDATED')
286
+ for project in projects:
287
+ print(f'{project["id"]:<8} {project["name"]:<32} {project.get("updated_at", "")}')
288
+
289
+
290
+ def command_create(args):
291
+ project = api_request('/api/projects', method='POST', payload={'name': args.name})
292
+ print(f'Created {project["name"]} (ID {project["id"]}).')
293
+
294
+
295
+ def command_push(args):
296
+ project = project_for(args.project)
297
+ archive_path, files, skipped, size = build_archive(Path(args.path))
298
+ try:
299
+ if not files:
300
+ raise LameCliError('No files to upload. Add project files or review your .lameignore rules.')
301
+ with archive_path.open('rb') as archive_file:
302
+ archive = archive_file.read()
303
+ result = api_request(
304
+ f'/api/projects/{project["id"]}/archive',
305
+ method='POST',
306
+ raw=archive,
307
+ content_type='application/zip',
308
+ )
309
+ finally:
310
+ remove_temporary_directory(archive_path.parent)
311
+ print(
312
+ f'Pushed {result.get("files", files)} file(s) to {project["name"]} '
313
+ f'({size / 1024:.1f} KB archive).'
314
+ )
315
+ if skipped:
316
+ print(f'Skipped {skipped} ignored, linked, or oversized file(s).')
317
+
318
+
319
+ def command_pull(args):
320
+ project = project_for(args.project)
321
+ destination = Path(args.path).resolve()
322
+ if destination.exists() and not destination.is_dir():
323
+ raise LameCliError(f'Download destination is not a directory: {destination}')
324
+ if destination.exists() and any(destination.iterdir()) and not args.force:
325
+ raise LameCliError(
326
+ f'{destination} is not empty. Use --force to merge downloaded files into it.'
327
+ )
328
+ archive_bytes = api_request(
329
+ f'/api/projects/{project["id"]}/archive',
330
+ download=True,
331
+ )
332
+ if len(archive_bytes) > MAX_ARCHIVE_BYTES:
333
+ raise LameCliError('The downloaded archive is larger than the 128 MB CLI limit.')
334
+ destination.mkdir(parents=True, exist_ok=True)
335
+ try:
336
+ extracted = set()
337
+ total_size = 0
338
+ with zipfile.ZipFile(io.BytesIO(archive_bytes)) as archive:
339
+ for entry in archive.infolist():
340
+ relative = Path(entry.filename)
341
+ if relative.is_absolute() or '..' in relative.parts or '\\' in entry.filename:
342
+ raise LameCliError('The project archive contains an unsafe file path.')
343
+ name = relative.as_posix().rstrip('/')
344
+ if (
345
+ not name
346
+ or len(relative.parts) > 10
347
+ or any(part in {'.', '..'} or not VALID_PATH_PART.fullmatch(part) for part in relative.parts)
348
+ ):
349
+ raise LameCliError('The project archive contains an unsafe file path.')
350
+ mode = entry.external_attr >> 16
351
+ if stat.S_ISLNK(mode):
352
+ raise LameCliError('The project archive contains a symbolic link.')
353
+ if not entry.is_dir():
354
+ if name.casefold() in extracted:
355
+ raise LameCliError('The project archive contains duplicate file names.')
356
+ extracted.add(name.casefold())
357
+ if entry.file_size > MAX_FILE_BYTES:
358
+ raise LameCliError(f'{entry.filename} exceeds the 128 MB per-file limit.')
359
+ total_size += entry.file_size
360
+ if total_size > 512 * 1024 * 1024:
361
+ raise LameCliError('The project exceeds the 512 MB unpacked size limit.')
362
+ target = (destination / relative).resolve()
363
+ if os.path.commonpath((str(destination), str(target))) != str(destination):
364
+ raise LameCliError('The project archive contains an unsafe file path.')
365
+ if entry.is_dir():
366
+ target.mkdir(parents=True, exist_ok=True)
367
+ continue
368
+ target.parent.mkdir(parents=True, exist_ok=True)
369
+ with archive.open(entry) as source, target.open('wb') as output:
370
+ output.write(source.read())
371
+ except (OSError, zipfile.BadZipFile) as error:
372
+ raise LameCliError(f'Could not extract the project archive: {error}') from error
373
+ print(f'Pulled {project["name"]} into {destination}.')
374
+
375
+
376
+ def command_rename(args):
377
+ project = project_for(args.project)
378
+ result = api_request(
379
+ f'/api/projects/{project["id"]}',
380
+ method='PATCH',
381
+ payload={'name': args.name},
382
+ )
383
+ print(f'Renamed project to {result["name"]}.')
384
+
385
+
386
+ def parser():
387
+ root = argparse.ArgumentParser(
388
+ prog='lame',
389
+ description='Sync local project folders with your Lame cloud workspace.',
390
+ )
391
+ commands = root.add_subparsers(dest='command', required=True)
392
+ login = commands.add_parser('login', help='save a short-lived token from Lame Projects')
393
+ login.add_argument('--server', default=DEFAULT_SERVER, help='Lame server URL')
394
+ login.set_defaults(handler=command_login)
395
+ logout = commands.add_parser('logout', help='revoke the CLI token and log out')
396
+ logout.set_defaults(handler=command_logout)
397
+ projects = commands.add_parser('projects', help='list cloud projects')
398
+ projects.set_defaults(handler=command_projects)
399
+ create = commands.add_parser('create', help='create a cloud project')
400
+ create.add_argument('name')
401
+ create.set_defaults(handler=command_create)
402
+ push = commands.add_parser('push', help='upload a local folder to a project')
403
+ push.add_argument('project', help='project name or ID')
404
+ push.add_argument('--path', default='.', help='local project folder (default: current folder)')
405
+ push.set_defaults(handler=command_push)
406
+ pull = commands.add_parser('pull', help='download a project into a local folder')
407
+ pull.add_argument('project', help='project name or ID')
408
+ pull.add_argument('--path', default='.', help='download folder (default: current folder)')
409
+ pull.add_argument('--force', action='store_true', help='merge into a non-empty folder')
410
+ pull.set_defaults(handler=command_pull)
411
+ rename = commands.add_parser('rename', help='rename a cloud project')
412
+ rename.add_argument('project', help='project name or ID')
413
+ rename.add_argument('name')
414
+ rename.set_defaults(handler=command_rename)
415
+ return root
416
+
417
+
418
+ def main():
419
+ args = parser().parse_args()
420
+ try:
421
+ args.handler(args)
422
+ except LameCliError as error:
423
+ print(f'lame: {error}', file=sys.stderr)
424
+ return 1
425
+ return 0
426
+
427
+
428
+ if __name__ == '__main__':
429
+ raise SystemExit(main())