v3: feature: verdi collab

.gitignore

@@ -64,3 +64,4 @@ docker-bake.override.json
 
 # dev files
 .dev
+.aep/

CLAUDE.md

@@ -1 +1,29 @@
 @AGENTS.md
+
+
+## Code
+
+The smallest change that satisfies the requirement. Prefer extending an existing function or module over adding a new one. No abstraction, configuration knob, or extensibility hook until there is a second caller that needs it.
+
+No defensive code for conditions that cannot currently occur. No compatibility shims for versions we do not support.
+
+Comments explain *why*, never *what*. If a comment restates the line below it, delete the comment. If the code needs a comment to be readable, first try renaming things.
+
+Delete code that a change makes dead. Do not leave it commented out — that is what git is for.
+
+## Tests
+
+Test the functionality, not the implementation. The minimum suite that would actually fail if the feature broke, and no more.
+
+Mock anything slow or external: network, filesystem beyond a tmpdir, databases, subprocesses, time, third-party APIs. CI time is a real cost.
+
+One test per behavior. No parametrized matrices covering combinations that cannot differ. No test helper frameworks, custom assertion DSLs, or fixture hierarchies built for a single test file — a test that needs its own framework to be readable is over-engineered.
+
+A test that cannot fail is worse than no test. Before adding one, know what break it catches.
+
+It's better to run pytest via "-n auto" to speed up
+
+
+## Development phases
+
+Don't worry about migration between development phases. All phases in this PR are still a PR, there're no users yet.

docs/source/howto/index.rst

@@ -17,6 +17,7 @@ How-To Guides
    data
    query
    share_data
+   collaborate
    archive_profile
    visualising_graphs
    installation

docs/source/reference/command_line.rst

@@ -106,6 +106,32 @@ Below is a list with all available subcommands.
       test       Run tests for the given code to check whether it is usable.
 
 
+.. _reference:command-line:verdi-collab:
+
+``verdi collab``
+----------------
+
+.. code:: console
+
+    Usage:  [OPTIONS] COMMAND [ARGS]...
+
+      Share provenance with the peers of a collab.
+
+    Options:
+      --help  Show this message and exit.
+
+    Commands:
+      init          Set up a profile as part of a collab.
+      link          Print the code that admits a newcomer to this collab.
+      log           Show the history of the pulls, pushes and extras refreshes of the...
+      map-computer  Treat calculations that ran on a peer computer as if they ran on a...
+      peer          Correct the entries of the peers of the collab.
+      pull          Fetch the new sealed provenance of peers and import it.
+      push          Send the new sealed provenance of this profile to peers.
+      rekey         Adopt the new token of a collab whose token was rotated.
+      rotate        Retire the token of the collab and mint a new one.
+
+
 .. _reference:command-line:verdi-computer:
 
 ``verdi computer``

src/aiida/cmdline/commands/__init__.py

@@ -17,6 +17,7 @@
     cmd_bug_report,
     cmd_calcjob,
     cmd_code,
+    cmd_collab,
     cmd_computer,
     cmd_config,
     cmd_daemon,

src/aiida/cmdline/commands/cmd_archive.py

@@ -465,6 +465,18 @@ def _gather_imports(archives: list[str], webpages: list[str] | None) -> list[tup
     return final_archives
 
 
+def _is_collab_thin_delta(archive_path: str) -> bool:
+    """Return whether the archive is a thin collab delta, which only ``verdi collab pull`` imports completely."""
+    from aiida.tools.archive.abstract import get_format
+
+    try:
+        with get_format().open(archive_path, mode='r') as reader:
+            return bool(reader.get_metadata().get('creation_parameters', {}).get('collab_thin_delta'))
+    except Exception:
+        # An archive this version cannot read yet is handled (or refused) by the import machinery itself.
+        return False
+
+
 def _import_archive_and_migrate(
     ctx: click.Context, archive: str, web_based: bool, import_kwargs: dict, try_migration: bool
 ) -> None:
@@ -502,6 +514,14 @@ def _import_archive_and_migrate(
             echo.echo_success('archive downloaded, proceeding with import')
 
         archive_path = str(archive_path)
+
+        if _is_collab_thin_delta(archive_path):
+            echo.echo_critical(
+                f'{archive} is a collab transfer delta, not a general-purpose archive: importing it here would '
+                'silently lose the links it carries to nodes outside of it. It is imported by `verdi collab pull` '
+                'on the destination profile.'
+            )
+
         echo.echo_report(f'starting import: {archive}')
         try:
             _import_archive(archive_path, archive_format=archive_format, **import_kwargs)

src/aiida/cmdline/commands/cmd_bug_report.py

@@ -226,6 +226,7 @@ def _get_log_files() -> dict[str, pathlib.Path]:
         'circus': filepaths['circus']['log'],
         'daemon': filepaths['daemon']['log'],
         'broker_service': filepaths['broker_service']['log'],
+        'collab': filepaths['collab']['log'],
     }
 
     for log_type, log_filepath in log_filepaths.items():